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

cryptnox_id_cli/cli/main.py

@@ -0,0 +1,117 @@
+"""CLI root group, global options and the error funnel."""
+
+from __future__ import annotations
+
+import json as _json
+import sys
+
+import click
+
+from cryptnox_id_cli import CLI_NAME, __version__
+from cryptnox_id_cli.cli import dryrun
+from cryptnox_id_cli.cli.commands import apdu as apdu_cmd
+from cryptnox_id_cli.cli.commands import doctor as doctor_cmd
+from cryptnox_id_cli.cli.commands import factory as factory_cmd
+from cryptnox_id_cli.cli.commands import fido as fido_cmd
+from cryptnox_id_cli.cli.commands import genuine as genuine_cmd
+from cryptnox_id_cli.cli.commands import info as info_cmd
+from cryptnox_id_cli.cli.commands import mifare as mifare_cmd
+from cryptnox_id_cli.cli.commands import piv as piv_cmd
+from cryptnox_id_cli.cli.commands import readers as readers_cmd
+from cryptnox_id_cli.cli.commands import report as report_cmd
+from cryptnox_id_cli.cli.commands import shell as shell_cmd
+from cryptnox_id_cli.cli.context import AppContext
+from cryptnox_id_cli.transport.errors import CryptnoxError
+
+
+def _report(app: AppContext | None, exc: CryptnoxError) -> None:
+    if app is not None and app.json:
+        sys.stdout.write(_json.dumps(exc.to_dict(), indent=2) + "\n")
+    elif app is not None:
+        app.out.error(str(exc))
+    else:  # error before context creation
+        click.echo(f"error: {exc}", err=True)
+
+
+class CryptnoxCLI(click.Group):
+    """Group that routes our own exceptions through the friendly error funnel."""
+
+    def invoke(self, ctx: click.Context) -> object:
+        try:
+            return super().invoke(ctx)
+        except CryptnoxError as exc:
+            app = ctx.obj if isinstance(ctx.obj, AppContext) else None
+            _report(app, exc)
+            sys.exit(getattr(exc, "exit_code", 1))
+
+
+@click.group(cls=CryptnoxCLI, context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name=CLI_NAME)
+@click.option("--reader", metavar="NAME|INDEX", help="Select PC/SC reader (default: Cryptnox/ACS).")
+@click.option("--json", "json_", is_flag=True, help="Machine-readable JSON output.")
+@click.option("--verbose", is_flag=True, help="Human-readable debug output (APDU trace to stderr).")
+@click.option("--apdu-log", metavar="FILE", help="Append a redacted APDU transcript to FILE.")
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Write nothing to the card: commands that can plan show the intended actions; "
+    "commands that cannot refuse to run (fail-closed).",
+)
+@click.option("--yes", is_flag=True, help="Skip destructive confirmation prompts.")
+@click.option("--timeout", type=int, default=15, show_default=True, help="Reader/card timeout (s).")
+@click.option("--no-color", is_flag=True, help="Disable coloured output.")
+@click.option(
+    "--elevated-result-out", hidden=True, help="Internal: capture result JSON (elevation)."
+)
+@click.pass_context
+def main(
+    ctx: click.Context,
+    reader: str | None,
+    json_: bool,
+    verbose: bool,
+    apdu_log: str | None,
+    dry_run: bool,
+    yes: bool,
+    timeout: int,
+    no_color: bool,
+    elevated_result_out: str | None,
+) -> None:
+    """Manage the Cryptnox multi-applet smartcard (PIV / FIDO2 / DESFire).
+
+    PIV management, factory pre-personalization and personalization run over a
+    contact or contactless reader; MIFARE DESFire needs a contactless reader; FIDO2
+    needs an Administrator terminal on Windows. Cryptnox/ACS readers are picked by default.
+    """
+    ctx.obj = AppContext(
+        reader=reader,
+        json=json_,
+        verbose=verbose,
+        apdu_log_path=apdu_log,
+        dry_run=dry_run,
+        yes=yes,
+        timeout=timeout,
+        no_color=no_color,
+        elevated_result_out=elevated_result_out,
+    )
+    ctx.call_on_close(ctx.obj.close)
+
+
+main.add_command(readers_cmd.command)
+main.add_command(info_cmd.command)
+main.add_command(doctor_cmd.command)
+main.add_command(apdu_cmd.command)
+main.add_command(piv_cmd.command)
+main.add_command(mifare_cmd.command)
+main.add_command(fido_cmd.command)
+main.add_command(genuine_cmd.command)
+main.add_command(report_cmd.command)
+main.add_command(factory_cmd.command)
+main.add_command(shell_cmd.command)
+
+# Enforce the --dry-run promise fail-closed: commands that cannot plan their card
+# operations refuse to run under --dry-run instead of silently executing for real.
+dryrun.install_guard(main)
+
+
+if __name__ == "__main__":
+    main()

cryptnox_id_cli/crypto/__init__.py

@@ -0,0 +1 @@
+"""Crypto helpers (X.509 inspection, PEM). Read-only in Phases 2-3."""

cryptnox_id_cli/crypto/attestation.py

@@ -0,0 +1,169 @@
+"""Offline verification of a PIV key-attestation chain.
+
+The pinned ``cryptography`` exposes no high-level path validator, so we walk the chain
+manually (the same approach as the genuineness check in ``docs/verify-genuine.md``):
+
+* name chaining   — each cert's issuer equals the next cert's subject
+* signature       — each cert is signed by the next cert's public key
+* validity        — each cert is within its not-before/not-after window
+* CA constraint   — every issuer (intermediate/root) asserts BasicConstraints CA=TRUE
+* anchoring       — the chain terminates at a **pinned** root (passed in by the caller);
+                    a root is trusted because it is pinned, never because it appears here
+
+The leaf comes off the card; ``intermediates`` is an **unordered candidate pool** (the bundled
+trust store holds several sibling CAs, and a card may present its chain in any order), and
+``roots`` are the pinned anchors. The path is built by matching each certificate's issuer name
+and then checking the signature, so sibling CAs in the pool cannot be mistaken for the issuer.
+An optional ``csr_spki`` enforces that the attested public key is the one in a CSR (the "same
+key as your CSR" property).
+"""
+
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass, field
+
+from cryptography import x509
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec, padding, rsa
+
+
+@dataclass
+class AttestationResult:
+    """Outcome of :func:`verify_attestation_chain` — JSON-friendly."""
+
+    verified: bool
+    reasons: list[str] = field(default_factory=list)  # empty iff verified
+    chain: list[str] = field(default_factory=list)  # subjects, leaf -> anchor
+    csr_match: bool | None = None  # None if no CSR was supplied
+    #: DER of each certificate on the path, leaf first — the certificates actually selected,
+    #: not the whole candidate pool. Kept out of ``to_dict`` (bytes are not JSON-friendly).
+    path_ders: list[bytes] = field(default_factory=list, repr=False)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "verified": self.verified,
+            "reasons": self.reasons,
+            "chain": self.chain,
+            "csr_match": self.csr_match,
+        }
+
+
+def _spki(cert: x509.Certificate) -> bytes:
+    return cert.public_key().public_bytes(
+        serialization.Encoding.DER, serialization.PublicFormat.SubjectPublicKeyInfo
+    )
+
+
+def _cn(cert: x509.Certificate) -> str:
+    return cert.subject.rfc4514_string()
+
+
+def _der(cert: x509.Certificate) -> bytes:
+    return cert.public_bytes(serialization.Encoding.DER)
+
+
+def _is_ca(cert: x509.Certificate) -> bool:
+    try:
+        return bool(cert.extensions.get_extension_for_class(x509.BasicConstraints).value.ca)
+    except x509.ExtensionNotFound:
+        return False
+
+
+def _signed_by(child: x509.Certificate, issuer: x509.Certificate) -> bool:
+    """True if ``issuer``'s public key verifies ``child``'s signature."""
+    hash_alg = child.signature_hash_algorithm
+    if hash_alg is None:  # e.g. Ed25519 — not used for these attestation certs
+        return False
+    pub = issuer.public_key()
+    try:
+        if isinstance(pub, ec.EllipticCurvePublicKey):
+            pub.verify(child.signature, child.tbs_certificate_bytes, ec.ECDSA(hash_alg))
+        elif isinstance(pub, rsa.RSAPublicKey):
+            pub.verify(child.signature, child.tbs_certificate_bytes, padding.PKCS1v15(), hash_alg)
+        else:  # unsupported issuer key type
+            return False
+    except InvalidSignature:
+        return False
+    return True
+
+
+def verify_attestation_chain(
+    leaf_der: bytes,
+    intermediate_ders: list[bytes],
+    root_ders: list[bytes],
+    *,
+    csr_spki: bytes | None = None,
+    at_time: datetime.datetime | None = None,
+) -> AttestationResult:
+    """Validate ``leaf -> intermediates -> pinned root`` and collect every failure reason."""
+    now = at_time or datetime.datetime.now(datetime.timezone.utc)
+    leaf = x509.load_der_x509_certificate(leaf_der)
+    pool = [x509.load_der_x509_certificate(d) for d in intermediate_ders]
+    roots = [x509.load_der_x509_certificate(d) for d in root_ders]
+
+    reasons: list[str] = []
+    chain = [_cn(leaf)]
+    path_ders = [leaf_der]
+
+    # "Same key as your CSR".
+    csr_match: bool | None = None
+    if csr_spki is not None:
+        csr_match = _spki(leaf) == csr_spki
+        if not csr_match:
+            reasons.append("attested public key does not match the CSR")
+
+    if not roots:
+        reasons.append("no pinned trust anchor available — cannot verify the chain")
+
+    def _check_validity(cert: x509.Certificate) -> None:
+        if now < cert.not_valid_before_utc or now > cert.not_valid_after_utc:
+            reasons.append(f"certificate {_cn(cert)!r} is outside its validity window")
+
+    child = leaf
+    used: set[bytes] = {leaf_der}
+    # One hop per available certificate is the most any acyclic path can need; `used` already
+    # rules out revisiting, so this only bounds a pathological pool.
+    for _ in range(len(pool) + len(roots) + 1):
+        _check_validity(child)
+
+        # Anchor first: a pinned root that issued this certificate ends the path.
+        anchor = next(
+            (r for r in roots if r.subject == child.issuer and _signed_by(child, r)), None
+        )
+        if anchor is not None:
+            _check_validity(anchor)
+            chain.append(_cn(anchor))
+            path_ders.append(_der(anchor))
+            break
+
+        # Otherwise look for the issuer among the intermediates, by name *then* signature —
+        # the pool holds sibling CAs, so position in the list means nothing.
+        named = [c for c in pool if c.subject == child.issuer and _der(c) not in used]
+        issuer = next((c for c in named if _is_ca(c) and _signed_by(child, c)), None) or next(
+            (c for c in named if _signed_by(child, c)), None
+        )
+        if issuer is None:
+            if named:  # right name, wrong key — a substituted or tampered certificate
+                reasons.append(f"signature on {_cn(child)!r} does not verify")
+            elif roots:  # nothing on hand issues this cert, and no pinned root does either
+                reasons.append(f"not anchored: no pinned root issues {_cn(child)!r}")
+            break  # (an empty `roots` already recorded its own reason above)
+
+        if not _is_ca(issuer):
+            reasons.append(f"issuer {_cn(issuer)!r} is not a CA (BasicConstraints)")
+        chain.append(_cn(issuer))
+        path_ders.append(_der(issuer))
+        used.add(_der(issuer))
+        child = issuer
+    else:  # pragma: no cover - only reachable if the bound above is ever wrong
+        reasons.append("chain too long — giving up before reaching a pinned root")
+
+    return AttestationResult(
+        verified=not reasons,
+        reasons=reasons,
+        chain=chain,
+        csr_match=csr_match,
+        path_ders=path_ders,
+    )

cryptnox_id_cli/crypto/csr.py

@@ -0,0 +1,135 @@
+"""Build CSRs and self-signed certs around an external (on-card) signer.
+
+The PIV private key never leaves the card, so we assemble the ASN.1 with
+``asn1crypto`` and sign the TBS bytes via a callback that runs GENERAL
+AUTHENTICATE on the card.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Callable
+
+from asn1crypto import algos, csr, keys, pem, x509
+from cryptography.hazmat.primitives.asymmetric.utils import encode_dss_signature
+
+# A signer takes the digest to sign and returns the signature bytes.
+Signer = Callable[[bytes], bytes]
+
+# mechanism id -> (hash func, signature-algorithm name, EC coord length or None for RSA)
+_ALG = {
+    0x11: (hashlib.sha256, "sha256_ecdsa", 32),
+    0x14: (hashlib.sha384, "sha384_ecdsa", 48),
+    0x07: (hashlib.sha256, "sha256_rsa", None),
+    0x05: (hashlib.sha256, "sha256_rsa", None),
+}
+
+_RDN = {
+    "CN": "common_name",
+    "O": "organization_name",
+    "OU": "organizational_unit_name",
+    "C": "country_name",
+    "L": "locality_name",
+    "ST": "state_or_province_name",
+    "E": "email_address",
+}
+
+
+def parse_subject(subject: str) -> x509.Name:
+    """Parse a one-line DN like 'CN=John Doe,O=Cryptnox,C=CH' into a Name."""
+    parts: dict[str, str] = {}
+    for rdn in subject.split(","):
+        key, sep, value = rdn.partition("=")
+        key = key.strip().upper()
+        if not sep or key not in _RDN:
+            raise ValueError(f"unsupported subject component {rdn.strip()!r}")
+        parts[_RDN[key]] = value.strip()
+    if not parts:
+        raise ValueError("empty subject")
+    return x509.Name.build(parts)
+
+
+def ensure_der_ecdsa(signature: bytes, coord_len: int) -> bytes:
+    """Return a DER ECDSA signature; convert from raw r||s if needed."""
+    if len(signature) == 2 * coord_len:  # raw r||s
+        r = int.from_bytes(signature[:coord_len], "big")
+        s = int.from_bytes(signature[coord_len:], "big")
+        return encode_dss_signature(r, s)
+    return signature  # already DER
+
+
+def _finalize_sig(mechanism: int, raw: bytes, coord_len: int | None) -> bytes:
+    if coord_len is not None:  # EC
+        return ensure_der_ecdsa(raw, coord_len)
+    return raw  # RSA: card returns the PKCS#1 signature as-is
+
+
+def build_csr(subject: str, public_key_der: bytes, mechanism: int, signer: Signer) -> bytes:
+    """Build a PEM PKCS#10 CSR, signing the request info on-card via ``signer``."""
+    hash_fn, sig_alg, coord = _ALG[mechanism]
+    info = csr.CertificationRequestInfo(
+        {
+            "version": "v1",
+            "subject": parse_subject(subject),
+            "subject_pk_info": keys.PublicKeyInfo.load(public_key_der),
+            "attributes": [],
+        }
+    )
+    signature = _finalize_sig(mechanism, signer(hash_fn(info.dump()).digest()), coord)
+    request = csr.CertificationRequest(
+        {
+            "certification_request_info": info,
+            "signature_algorithm": algos.SignedDigestAlgorithm({"algorithm": sig_alg}),
+            "signature": signature,
+        }
+    )
+    return pem.armor("CERTIFICATE REQUEST", request.dump())
+
+
+def build_self_signed(
+    subject: str,
+    public_key_der: bytes,
+    mechanism: int,
+    signer: Signer,
+    *,
+    serial: int,
+    not_before: str,
+    not_after: str,
+) -> bytes:
+    """Build a PEM self-signed X.509 cert (dev/test), signed on-card.
+
+    ``not_before``/``not_after`` are ISO datetimes (passed in to avoid using the
+    clock here); ``serial`` is a positive integer.
+    """
+    hash_fn, sig_alg, coord = _ALG[mechanism]
+    name = parse_subject(subject)
+    alg = algos.SignedDigestAlgorithm({"algorithm": sig_alg})
+    tbs = x509.TbsCertificate(
+        {
+            "version": "v3",
+            "serial_number": serial,
+            "signature": alg,
+            "issuer": name,
+            "validity": {
+                "not_before": _time(not_before),
+                "not_after": _time(not_after),
+            },
+            "subject": name,
+            "subject_public_key_info": keys.PublicKeyInfo.load(public_key_der),
+        }
+    )
+    signature = _finalize_sig(mechanism, signer(hash_fn(tbs.dump()).digest()), coord)
+    cert = x509.Certificate(
+        {"tbs_certificate": tbs, "signature_algorithm": alg, "signature_value": signature}
+    )
+    return pem.armor("CERTIFICATE", cert.dump())
+
+
+def _time(iso: str) -> x509.Time:
+    """Encode an ISO datetime as the RFC 5280-correct ASN.1 time: UTCTime for years
+    < 2050, GeneralizedTime for 2050+ (UTCTime's 2-digit year wraps otherwise)."""
+    from datetime import datetime
+
+    dt = datetime.fromisoformat(iso)
+    field = "utc_time" if dt.year < 2050 else "general_time"
+    return x509.Time({field: dt})

cryptnox_id_cli/crypto/piv_objects.py

@@ -0,0 +1,79 @@
+"""Generators for basic PIV data objects (CHUID, CCC, Discovery).
+
+These produce minimal, well-formed objects suitable for a dev/test card so the
+operator never hand-crafts TLV. FASC-N / Card Identifier use placeholder values;
+they are NOT federally meaningful credentials.
+"""
+
+from __future__ import annotations
+
+import os
+
+from cryptnox_id_cli.applets.piv.constants import PIV_AID
+from cryptnox_id_cli.util import tlv
+
+# CHUID element tags (SP 800-73-4 Part 1 Table 9).
+_FASC_N = 0x30
+_GUID = 0x34
+_EXPIRATION = 0x35
+_ISSUER_SIGNATURE = 0x3E
+_ERROR_DETECTION = 0xFE
+
+
+def generate_chuid(guid: bytes | None = None, expiration: str = "20400101") -> bytes:
+    """Build a minimal CHUID object value (the content wrapped by tag 0x53).
+
+    ``guid`` defaults to a random 16-byte value; ``expiration`` is YYYYMMDD ASCII.
+    The issuer signature (0x3E) is left empty (unsigned dev CHUID).
+    """
+    guid = guid or os.urandom(16)
+    if len(guid) != 16:
+        raise ValueError("GUID must be 16 bytes")
+    return (
+        tlv.build(_FASC_N, bytes(25))  # placeholder FASC-N
+        + tlv.build(_GUID, guid)
+        + tlv.build(_EXPIRATION, expiration.encode("ascii"))
+        + tlv.build(_ISSUER_SIGNATURE, b"")
+        + tlv.build(_ERROR_DETECTION, b"")
+    )
+
+
+def generate_ccc(card_id: bytes | None = None) -> bytes:
+    """Build a minimal Card Capability Container value (content wrapped by 0x53)."""
+    # F0 Card Identifier (21 bytes): GSC-RID A000000116 + mfr/card-type + 14-byte id.
+    card_id = card_id or (bytes.fromhex("A000000116") + b"\xff\x02" + os.urandom(14))
+    if len(card_id) != 21:
+        raise ValueError("CCC card identifier must be 21 bytes")
+    return (
+        tlv.build(0xF0, card_id)
+        + tlv.build(0xF1, b"\x21")  # capability container version
+        + tlv.build(0xF2, b"\x21")  # capability grammar version
+        + tlv.build(0xF3, b"")  # applications CardURL
+        + tlv.build(0xF4, b"\x00")  # PKCS#15
+        + tlv.build(0xF5, b"\x10")  # registered data model number
+        + tlv.build(0xF6, b"")  # access control rule table
+        + tlv.build(0xF7, b"")  # card APDUs
+        + tlv.build(0xFA, b"")  # redirection tag
+        + tlv.build(0xFB, b"")  # capability tuples
+        + tlv.build(0xFC, b"")  # status tuples
+        + tlv.build(0xFD, b"")  # next CCC
+        + tlv.build(0xFE, b"")  # error detection
+    )
+
+
+# PIN Usage Policy (SP 800-73-4 Part 1, Discovery Object tag 0x5F2F): first byte
+# 0x40 = the PIV Application PIN (key ref 0x80) is present; second byte 0x10 = it is
+# the primary PIN. We deliberately do NOT offer the Global PIN (first byte 0x20 /
+# second byte 0x20, key ref 0x00) -- see docs/adr/0001-piv-application-pin-not-global-pin.md.
+_PIN_USAGE_APPLICATION_PRIMARY = b"\x40\x10"
+
+
+def generate_discovery() -> bytes:
+    """Build the Discovery Object (the 0x7E TLV itself, not 0x53-wrapped).
+
+    The PIN Usage Policy is fixed to "Application PIN, primary" (0x40 0x10). The Global
+    PIN is intentionally not supported (ADR-0001), so this is not configurable.
+    """
+    return tlv.build_constructed(
+        0x7E, tlv.build(0x4F, PIV_AID) + tlv.build(0x5F2F, _PIN_USAGE_APPLICATION_PRIMARY)
+    )

cryptnox_id_cli/crypto/x509util.py

@@ -0,0 +1,37 @@
+"""Minimal X.509 inspection for PIV certificate objects (read-only)."""
+
+from __future__ import annotations
+
+import hashlib
+
+from cryptography import x509
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec, rsa
+
+
+def to_pem(der: bytes) -> bytes:
+    return x509.load_der_x509_certificate(der).public_bytes(serialization.Encoding.PEM)
+
+
+def _key_description(cert: x509.Certificate) -> str:
+    pub = cert.public_key()
+    if isinstance(pub, rsa.RSAPublicKey):
+        return f"RSA-{pub.key_size}"
+    if isinstance(pub, ec.EllipticCurvePublicKey):
+        return f"EC-{pub.curve.name}"
+    return type(pub).__name__
+
+
+def describe_certificate(der: bytes) -> dict[str, object]:
+    """Return a JSON-able summary of a DER certificate."""
+    cert = x509.load_der_x509_certificate(der)
+    return {
+        "subject": cert.subject.rfc4514_string(),
+        "issuer": cert.issuer.rfc4514_string(),
+        "serial": format(cert.serial_number, "X"),
+        "not_before": cert.not_valid_before_utc.isoformat(),
+        "not_after": cert.not_valid_after_utc.isoformat(),
+        "signature_algorithm": cert.signature_algorithm_oid._name,
+        "public_key": _key_description(cert),
+        "sha256_fingerprint": hashlib.sha256(der).hexdigest().upper(),
+    }

cryptnox_id_cli/output/__init__.py

@@ -0,0 +1,5 @@
+"""Output rendering: one result object rendered as human tables or JSON."""
+
+from cryptnox_id_cli.output.render import Output
+
+__all__ = ["Output"]

cryptnox_id_cli/output/render.py

@@ -0,0 +1,106 @@
+"""Unified output: each command builds a JSON-able payload plus a human renderer."""
+
+from __future__ import annotations
+
+import json as _json
+import sys
+from collections.abc import Callable
+
+from rich.console import Console
+from rich.table import Table
+
+
+class Output:
+    """Holds the rendering policy (JSON vs human, colour) for one CLI invocation."""
+
+    def __init__(
+        self,
+        *,
+        json: bool = False,
+        no_color: bool = False,
+        verbose: bool = False,
+        result_path: str | None = None,
+    ) -> None:
+        self.json = json
+        self.verbose = verbose
+        # When set (elevated child), the result payload is also written here as JSON so
+        # the non-elevated parent can surface it in the original console.
+        self.result_path = result_path
+        # In JSON mode we keep stdout pure (no rich), so diagnostics go to stderr.
+        self.console = Console(no_color=no_color, highlight=False, soft_wrap=True)
+        self.err = Console(stderr=True, no_color=no_color, highlight=False, soft_wrap=True)
+
+    # -- results ------------------------------------------------------------ #
+    def result(self, payload: dict, render_human: Callable[[Console], None]) -> None:
+        if self.result_path:
+            with open(self.result_path, "w", encoding="utf-8") as fh:
+                fh.write(_json.dumps(payload, indent=2, default=str) + "\n")
+        if self.json:
+            sys.stdout.write(_json.dumps(payload, indent=2, default=str) + "\n")
+        else:
+            render_human(self.console)
+
+    # -- ad-hoc messages (suppressed or routed to stderr in JSON mode) ------ #
+    def info(self, message: str) -> None:
+        if not self.json:
+            self.console.print(message)
+
+    def detail(self, message: str) -> None:
+        if self.verbose and not self.json:
+            self.console.print(f"[dim]{message}[/dim]")
+
+    def note(self, message: str) -> None:
+        """A dim, always-shown informational line (e.g. a satisfied requirement)."""
+        target = self.err if self.json else self.console
+        target.print(f"[dim]note: {message}[/dim]")
+
+    def warn(self, message: str) -> None:
+        target = self.err if self.json else self.console
+        target.print(f"[yellow]warning:[/yellow] {message}")
+
+    def error(self, message: str) -> None:
+        self.err.print(f"[red]error:[/red] {message}")
+
+    def success(self, message: str) -> None:
+        if not self.json:
+            self.console.print(f"[green]OK[/green] {message}")
+
+    # -- helpers ------------------------------------------------------------ #
+    def table(self, *headers: str, title: str | None = None) -> Table:
+        table = Table(title=title, show_lines=False, header_style="bold")
+        for h in headers:
+            table.add_column(h)
+        return table
+
+    def print(self, renderable: object) -> None:
+        if not self.json:
+            self.console.print(renderable)
+
+
+def state_style(label: str) -> str:
+    """Colour a state label for human output."""
+    good = {
+        "PivPersonalized",
+        "FidoPersonalized",
+        "DesfireReachable",
+        "CardPresent",
+        "GenuinenessPersonalized",
+    }
+    warn = {
+        "PivPrePersonalized",
+        "PivPartiallyPersonalized",
+        "PivSelectable",
+        "FidoSelectable",
+        "DesfireNeedsContactlessReader",
+        "DesfireNoAnswerContactless",
+        "FidoBlockedByOS",
+        "GenuinenessPresent",
+        "GenuinenessNeedsContactReader",
+    }
+    if label in good:
+        return f"[green]{label}[/green]"
+    if label in warn:
+        return f"[yellow]{label}[/yellow]"
+    if label in {"Unknown"} or label.endswith("NotPresent"):
+        return f"[dim]{label}[/dim]"
+    return label

cryptnox_id_cli/secrets/__init__.py

@@ -0,0 +1,5 @@
+"""Secret handling: a single redaction chokepoint and secret-input resolver.
+
+Nothing in this CLI prints or logs a secret except through code that has first
+passed it through :class:`~cryptnox_id_cli.secrets.redaction.Redactor`.
+"""