tiny-pki 0.1.0__py3-none-any.whl

tiny_pki/__init__.py

@@ -0,0 +1,110 @@
+"""tiny-pki — private CA crypto primitives and CLI.
+
+Core APIs are bytes-in / bytes-out (no filesystem, no Django). Extracted and
+generalized under MIT from ``the-hcma/my-tracks`` ``app/pki.py``.
+"""
+
+from __future__ import annotations
+
+from tiny_pki.bundle import generate_pkcs12
+from tiny_pki.check import (
+    CertificateKind,
+    CertificateStatus,
+    Status,
+    check_certificate,
+    check_crl,
+    default_warning_window,
+    worst_status,
+)
+from tiny_pki.constants import (
+    ALLOWED_KEY_SIZES,
+    APPLE_MAX_SERVER_VALIDITY_DAYS,
+    CLOCK_SKEW_BACKDATE,
+    DEFAULT_CA_KEY_SIZE,
+    DEFAULT_CA_VALIDITY_DAYS,
+    DEFAULT_CLIENT_VALIDITY_DAYS,
+    DEFAULT_CRL_VALIDITY_DAYS,
+    DEFAULT_KEY_TYPE,
+    DEFAULT_LEAF_KEY_SIZE,
+    DEFAULT_ORGANIZATION_NAME,
+    DEFAULT_SERVER_VALIDITY_DAYS,
+    KEY_TYPES,
+    MAX_CA_WARNING_DAYS,
+    MAX_CLIENT_VALIDITY_DAYS,
+    MAX_LEAF_WARNING_DAYS,
+    MAX_SERVER_VALIDITY_DAYS,
+    MAX_STORE_CRL_VALIDITY_DAYS,
+    MAX_VALIDITY_DAYS,
+    MIN_PKCS12_PASSWORD_LENGTH,
+    VALIDITY_PRESETS,
+    KeyType,
+)
+from tiny_pki.errors import TinyPkiError, TinyPkiWarning
+from tiny_pki.inspect import (
+    get_certificate_expiry,
+    get_certificate_fingerprint,
+    get_certificate_issuer,
+    get_certificate_metadata,
+    get_certificate_sans,
+    get_certificate_serial_number,
+    get_certificate_subject,
+    is_certificate_self_signed,
+)
+from tiny_pki.issue import (
+    generate_ca_certificate,
+    generate_client_certificate,
+    generate_server_certificate,
+    max_leaf_validity_days,
+)
+from tiny_pki.revoke import generate_crl
+from tiny_pki.version import package_version
+
+__version__ = package_version()
+
+__all__ = [
+    "ALLOWED_KEY_SIZES",
+    "APPLE_MAX_SERVER_VALIDITY_DAYS",
+    "CLOCK_SKEW_BACKDATE",
+    "CertificateKind",
+    "CertificateStatus",
+    "DEFAULT_CA_KEY_SIZE",
+    "DEFAULT_CA_VALIDITY_DAYS",
+    "DEFAULT_CLIENT_VALIDITY_DAYS",
+    "DEFAULT_CRL_VALIDITY_DAYS",
+    "DEFAULT_KEY_TYPE",
+    "DEFAULT_LEAF_KEY_SIZE",
+    "DEFAULT_ORGANIZATION_NAME",
+    "DEFAULT_SERVER_VALIDITY_DAYS",
+    "KEY_TYPES",
+    "KeyType",
+    "MAX_CA_WARNING_DAYS",
+    "MAX_CLIENT_VALIDITY_DAYS",
+    "MAX_LEAF_WARNING_DAYS",
+    "MAX_SERVER_VALIDITY_DAYS",
+    "MAX_STORE_CRL_VALIDITY_DAYS",
+    "MAX_VALIDITY_DAYS",
+    "MIN_PKCS12_PASSWORD_LENGTH",
+    "Status",
+    "TinyPkiError",
+    "TinyPkiWarning",
+    "VALIDITY_PRESETS",
+    "__version__",
+    "check_certificate",
+    "check_crl",
+    "default_warning_window",
+    "generate_ca_certificate",
+    "generate_client_certificate",
+    "generate_crl",
+    "generate_pkcs12",
+    "generate_server_certificate",
+    "get_certificate_expiry",
+    "get_certificate_fingerprint",
+    "get_certificate_issuer",
+    "get_certificate_metadata",
+    "get_certificate_sans",
+    "get_certificate_serial_number",
+    "get_certificate_subject",
+    "is_certificate_self_signed",
+    "max_leaf_validity_days",
+    "worst_status",
+]

tiny_pki/_build_metadata.py

@@ -0,0 +1,6 @@
+"""Autogenerated by scripts/embed_build_metadata — do not hand-edit."""
+
+from __future__ import annotations
+
+EMBEDDED_COMMIT: str = 'c596cc82e3fa'
+EMBEDDED_VERSION: str = '0.1.0'

tiny_pki/_fsutil.py

@@ -0,0 +1,55 @@
+"""Atomic file writes that never follow a symlink at the destination."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import tempfile
+from pathlib import Path
+
+
+def write_file_atomic(path: Path, data: bytes, *, mode: int) -> None:
+    """Replace ``path`` with ``data`` (file mode ``mode``) via a temp file and ``rename``.
+
+    A symlink already at ``path`` is refused. The temp file is created with
+    ``O_EXCL`` in the destination directory, and ``os.replace`` swaps the
+    directory entry instead of following a link, so a symlink planted between
+    the check and the rename is replaced rather than written through. Readers
+    see either the old file or the complete new one, never a truncated file.
+    """
+    if path.is_symlink():
+        raise ValueError(f"Expected {path} to not already exist as a symlink")
+    directory = path.parent
+    fd, tmp_name = tempfile.mkstemp(dir=directory, prefix=f".{path.name}.", suffix=".tmp")
+    tmp = Path(tmp_name)
+    try:
+        try:
+            fchmod = getattr(os, "fchmod", None)
+            if fchmod is not None:
+                fchmod(fd, mode)
+            else:
+                tmp.chmod(mode)
+            view = memoryview(data)
+            while view:
+                written = os.write(fd, view)
+                if written <= 0:
+                    raise OSError(f"Expected progress writing {path}, got {written} bytes")
+                view = view[written:]
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        os.replace(tmp, path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+    _fsync_directory(directory)
+
+
+def _fsync_directory(directory: Path) -> None:
+    """Persist the rename; best effort because some platforms cannot open a directory."""
+    with contextlib.suppress(OSError):
+        dir_fd = os.open(directory, os.O_RDONLY)
+        try:
+            os.fsync(dir_fd)
+        finally:
+            os.close(dir_fd)

tiny_pki/_keys.py

@@ -0,0 +1,74 @@
+"""Internal helpers for generating and loading RSA and ECDSA P-256 private keys."""
+
+from __future__ import annotations
+
+from cryptography import x509
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec, rsa
+
+from tiny_pki.constants import ALLOWED_KEY_SIZES, KEY_TYPES
+from tiny_pki.errors import TinyPkiError
+
+PrivateKey = rsa.RSAPrivateKey | ec.EllipticCurvePrivateKey
+
+
+def generate_private_key(rsa_key_size: int | None) -> PrivateKey:
+    """Generate the key :func:`require_key_params` resolved: RSA of that size, or P-256 for ``None``."""
+    if rsa_key_size is None:
+        return ec.generate_private_key(ec.SECP256R1())
+    return rsa.generate_private_key(public_exponent=65537, key_size=rsa_key_size)
+
+
+def load_private_key(key_pem: bytes) -> PrivateKey:
+    """Load an unencrypted RSA or ECDSA P-256 private key from PEM bytes.
+
+    Raises:
+        TinyPkiError: If the PEM is not an unencrypted RSA or P-256 private key
+            (including when cryptography raises ``TypeError`` for an
+            encrypted key with ``password=None``).
+    """
+    try:
+        key = serialization.load_pem_private_key(key_pem, password=None)
+    except TypeError as exc:
+        raise TinyPkiError(
+            "Expected an unencrypted PEM private key; got an encrypted key "
+            f"(password was not given but private key is encrypted): {exc}"
+        ) from exc
+    if isinstance(key, rsa.RSAPrivateKey):
+        return key
+    if isinstance(key, ec.EllipticCurvePrivateKey) and isinstance(key.curve, ec.SECP256R1):
+        return key
+    raise TinyPkiError(f"Expected an RSA or ECDSA P-256 private key, got {_describe(key)}")
+
+
+def load_ca_private_key(ca_cert: x509.Certificate, ca_key_pem: bytes) -> PrivateKey:
+    """Load the CA key with :func:`load_private_key` and require it to match ``ca_cert``.
+
+    Raises:
+        TinyPkiError: If the key cannot be loaded or belongs to a different certificate.
+    """
+    key = load_private_key(ca_key_pem)
+    spki = serialization.Encoding.DER, serialization.PublicFormat.SubjectPublicKeyInfo
+    if key.public_key().public_bytes(*spki) != ca_cert.public_key().public_bytes(*spki):
+        raise TinyPkiError("Expected the CA private key to match the CA certificate's public key")
+    return key
+
+
+def require_key_params(key_type: object, key_size: object, *, default_size: int) -> int | None:
+    """Validate ``key_type`` / ``key_size`` and return the RSA size to use (``None`` for EC)."""
+    if key_type not in KEY_TYPES:
+        raise TinyPkiError(f"Expected key_type in {KEY_TYPES}, got {key_type!r}")
+    if key_type == "ec-p256":
+        if key_size is not None:
+            raise TinyPkiError(f"Expected no key_size with key_type 'ec-p256' (P-256 has a fixed size), got {key_size}")
+        return None
+    size = default_size if key_size is None else key_size
+    if isinstance(size, bool) or not isinstance(size, int) or size not in ALLOWED_KEY_SIZES:
+        raise TinyPkiError(f"Expected key_size in {ALLOWED_KEY_SIZES}, got {size!r}")
+    return size
+
+
+def _describe(key: object) -> str:
+    if isinstance(key, ec.EllipticCurvePrivateKey):
+        return f"an EC key on {key.curve.name}"
+    return type(key).__name__

tiny_pki/bundle.py

@@ -0,0 +1,59 @@
+"""PKCS#12 (.p12) bundling for client handoff."""
+
+from __future__ import annotations
+
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.serialization import pkcs12
+
+from tiny_pki._keys import load_private_key
+from tiny_pki.constants import MIN_PKCS12_PASSWORD_LENGTH
+from tiny_pki.errors import TinyPkiError
+
+
+def generate_pkcs12(
+    cert_pem: bytes,
+    key_pem: bytes,
+    ca_cert_pem: bytes,
+    friendly_name: str,
+    password: bytes,
+    *,
+    legacy: bool = False,
+) -> bytes:
+    """Bundle cert + key + CA chain into a password-protected PKCS#12 archive.
+
+    By default the bundle uses ``cryptography``'s best available encryption
+    (AES-256-CBC with PBKDF2-HMAC-SHA256 and an HMAC-SHA256 MAC). ``legacy=True``
+    uses PBES1 3DES with a SHA-1 MAC instead, for older Android / Apple keychains
+    that cannot import the modern format; only use it when a device requires it.
+
+    Raises:
+        TinyPkiError: If ``friendly_name`` is empty or ``password`` is shorter than
+            ``MIN_PKCS12_PASSWORD_LENGTH`` bytes.
+    """
+    if not friendly_name or not friendly_name.strip():
+        raise TinyPkiError("Expected a non-empty friendly_name")
+    if len(password) < MIN_PKCS12_PASSWORD_LENGTH:
+        raise TinyPkiError(f"Expected a password of at least {MIN_PKCS12_PASSWORD_LENGTH} bytes, got {len(password)}")
+
+    cert = x509.load_pem_x509_certificate(cert_pem)
+    key = load_private_key(key_pem)
+    ca_cert = x509.load_pem_x509_certificate(ca_cert_pem)
+
+    encryption: serialization.KeySerializationEncryption
+    if legacy:
+        encryption = (
+            serialization.PrivateFormat.PKCS12.encryption_builder()
+            .key_cert_algorithm(pkcs12.PBES.PBESv1SHA1And3KeyTripleDESCBC)
+            .hmac_hash(hashes.SHA1())
+            .build(password)
+        )
+    else:
+        encryption = serialization.BestAvailableEncryption(password)
+    return pkcs12.serialize_key_and_certificates(
+        name=friendly_name.encode(),
+        key=key,
+        cert=cert,
+        cas=[ca_cert],
+        encryption_algorithm=encryption,
+    )

tiny_pki/check.py

@@ -0,0 +1,318 @@
+"""Expiry and validity checks for certificates and CRLs (PEM in, status out).
+
+A check answers "is this artifact usable now, and will it still be usable at the
+cutoff?". The cutoff is ``now + within``, ``by``, or the earlier of the two;
+with neither, it is ``now + default_warning_window(...)``.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from enum import StrEnum
+from typing import Literal
+
+from cryptography import x509
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric import ec, ed448, ed25519, rsa
+from cryptography.x509.oid import ExtendedKeyUsageOID, NameOID
+
+from tiny_pki.constants import MAX_CA_WARNING_DAYS, MAX_LEAF_WARNING_DAYS
+from tiny_pki.errors import TinyPkiError
+
+type CertificateKind = Literal["ca", "client", "crl", "server", "unknown"]
+
+
+@dataclass(frozen=True)
+class CertificateStatus:
+    """Outcome of :func:`check_certificate` or :func:`check_crl`.
+
+    ``not_after`` is the effective end of validity: for a leaf checked against
+    its CA, the earlier of the leaf's and the CA's ``notAfter``. The default
+    warning window still follows the leaf's own lifetime (its renewal cadence). For a CRL,
+    ``not_before`` / ``not_after`` are ``lastUpdate`` / ``nextUpdate``.
+    """
+
+    kind: CertificateKind
+    subject: str
+    issuer: str
+    serial_number: int | None
+    not_before: datetime
+    not_after: datetime | None
+    cutoff: datetime
+    days_remaining: int | None
+    status: Status
+    reasons: tuple[str, ...]
+
+
+class Status(StrEnum):
+    """Check outcome, declared from least to most severe."""
+
+    OK = "ok"
+    EXPIRING = "expiring"
+    NOT_YET_VALID = "not_yet_valid"
+    EXPIRED = "expired"
+    REVOKED = "revoked"
+    UNTRUSTED = "untrusted"
+
+    @property
+    def severity(self) -> int:
+        """Position in the declaration order; higher is worse."""
+        return list(Status).index(self)
+
+
+def check_certificate(
+    cert_pem: bytes,
+    *,
+    now: datetime | None = None,
+    within: timedelta | None = None,
+    by: datetime | None = None,
+    ca_cert_pem: bytes | None = None,
+    crl_pem: bytes | None = None,
+) -> CertificateStatus:
+    """Check a certificate's validity now and at the cutoff.
+
+    Args:
+        cert_pem: The certificate to check.
+        now: Evaluation time (timezone-aware); defaults to the current time.
+        within: Flag certificates that expire within this window of ``now``.
+        by: Flag certificates that expire on or before this instant.
+        ca_cert_pem: The issuing CA. When given, a bad issuer or signature makes
+            the result ``UNTRUSTED``, and a CA that expires first shortens the
+            effective validity.
+        crl_pem: A CRL from the same CA; a listed serial makes the result
+            ``REVOKED``. A CRL past its ``nextUpdate`` makes the result
+            ``UNTRUSTED`` (revocation status unknown), since an old CRL may
+            predate a revocation. Requires ``ca_cert_pem`` so the CRL's
+            signature can be verified.
+
+    Raises:
+        TinyPkiError: On naive datetimes, a negative ``within``, a ``ca_cert_pem``
+            that is not a CA certificate, a CRL without a CA, or a CRL not signed
+            by the given CA.
+    """
+    now = _require_aware(now or datetime.now(UTC), "now")
+    cert = x509.load_pem_x509_certificate(cert_pem)
+    kind = _certificate_kind(cert)
+    not_before = cert.not_valid_before_utc
+    not_after = cert.not_valid_after_utc
+    window = default_warning_window(kind, not_after - not_before)
+    reasons: list[tuple[Status, str]] = []
+
+    if crl_pem is not None and ca_cert_pem is None:
+        raise TinyPkiError("Expected ca_cert_pem with crl_pem so the CRL signature can be verified")
+    if ca_cert_pem is not None:
+        ca_cert = _load_ca(ca_cert_pem)
+        if not _is_issued_by(cert, ca_cert):
+            reasons.append((Status.UNTRUSTED, f"not issued by {_name_label(ca_cert.subject)}"))
+        elif ca_cert.not_valid_after_utc < not_after:
+            not_after = ca_cert.not_valid_after_utc
+            reasons.append((Status.OK, f"CA expires first ({not_after.isoformat()})"))
+        if crl_pem is not None:
+            crl = x509.load_pem_x509_crl(crl_pem)
+            if not _crl_signed_by(crl, ca_cert):
+                raise TinyPkiError(f"Expected a CRL signed by {_name_label(ca_cert.subject)}")
+            revoked = crl.get_revoked_certificate_by_serial_number(cert.serial_number)
+            if revoked is not None:
+                reasons.append((Status.REVOKED, f"revoked on {revoked.revocation_date_utc.isoformat()}"))
+            next_update = crl.next_update_utc
+            if next_update is not None and now >= next_update:
+                reasons.append(
+                    (Status.UNTRUSTED, f"CRL expired on {next_update.isoformat()}; revocation status unknown")
+                )
+
+    cutoff = _cutoff(now, within=within, by=by, default=window)
+    reasons.extend(_time_reasons(now, not_before, not_after, cutoff))
+    return _result(
+        kind=kind,
+        subject=_name_label(cert.subject),
+        issuer=_name_label(cert.issuer),
+        serial_number=cert.serial_number,
+        not_before=not_before,
+        not_after=not_after,
+        now=now,
+        cutoff=cutoff,
+        reasons=reasons,
+    )
+
+
+def check_crl(
+    crl_pem: bytes,
+    *,
+    now: datetime | None = None,
+    within: timedelta | None = None,
+    by: datetime | None = None,
+    ca_cert_pem: bytes | None = None,
+) -> CertificateStatus:
+    """Check a CRL's freshness: ``EXPIRED`` once ``nextUpdate`` passes.
+
+    With ``ca_cert_pem``, a CRL not signed by that CA is ``UNTRUSTED``. A CRL
+    without ``nextUpdate`` never goes stale and is reported as ``OK``.
+
+    Raises:
+        TinyPkiError: On naive datetimes, a negative ``within``, or a
+            ``ca_cert_pem`` that is not a CA certificate.
+    """
+    now = _require_aware(now or datetime.now(UTC), "now")
+    crl = x509.load_pem_x509_crl(crl_pem)
+    reasons: list[tuple[Status, str]] = []
+    if ca_cert_pem is not None:
+        ca_cert = _load_ca(ca_cert_pem)
+        if not _crl_signed_by(crl, ca_cert):
+            reasons.append((Status.UNTRUSTED, f"not signed by {_name_label(ca_cert.subject)}"))
+    not_before = crl.last_update_utc
+    not_after = crl.next_update_utc
+    if not_after is None:
+        cutoff = _cutoff(now, within=within, by=by, default=timedelta(0))
+        reasons.append((Status.OK, "no nextUpdate"))
+    else:
+        window = default_warning_window("crl", not_after - not_before)
+        cutoff = _cutoff(now, within=within, by=by, default=window)
+        reasons.extend(_time_reasons(now, not_before, not_after, cutoff))
+    try:
+        crl_number: int | None = crl.extensions.get_extension_for_class(x509.CRLNumber).value.crl_number
+    except x509.ExtensionNotFound:
+        crl_number = None
+    issuer = _name_label(crl.issuer)
+    return _result(
+        kind="crl",
+        subject=issuer,
+        issuer=issuer,
+        serial_number=crl_number,
+        not_before=not_before,
+        not_after=not_after,
+        now=now,
+        cutoff=cutoff,
+        reasons=reasons,
+    )
+
+
+def default_warning_window(kind: CertificateKind, lifetime: timedelta) -> timedelta:
+    """One third of ``lifetime``, capped at 180 days for a CA and 30 days for leaves.
+
+    CRLs are not capped: their window is already short.
+    """
+    window = max(lifetime, timedelta(0)) / 3
+    if kind == "crl":
+        return window
+    cap_days = MAX_CA_WARNING_DAYS if kind == "ca" else MAX_LEAF_WARNING_DAYS
+    return min(window, timedelta(days=cap_days))
+
+
+def worst_status(results: list[CertificateStatus]) -> Status:
+    """Return the most severe status in ``results`` (``OK`` when empty)."""
+    return max((r.status for r in results), key=lambda s: s.severity, default=Status.OK)
+
+
+_CRL_ISSUER_KEY_TYPES = (rsa.RSAPublicKey, ec.EllipticCurvePublicKey, ed25519.Ed25519PublicKey, ed448.Ed448PublicKey)
+
+
+def _certificate_kind(cert: x509.Certificate) -> CertificateKind:
+    try:
+        if cert.extensions.get_extension_for_class(x509.BasicConstraints).value.ca:
+            return "ca"
+    except x509.ExtensionNotFound:
+        pass
+    try:
+        usages = cert.extensions.get_extension_for_class(x509.ExtendedKeyUsage).value
+    except x509.ExtensionNotFound:
+        return "unknown"
+    if ExtendedKeyUsageOID.SERVER_AUTH in usages:
+        return "server"
+    if ExtendedKeyUsageOID.CLIENT_AUTH in usages:
+        return "client"
+    return "unknown"
+
+
+def _crl_signed_by(crl: x509.CertificateRevocationList, ca_cert: x509.Certificate) -> bool:
+    key = ca_cert.public_key()
+    if not isinstance(
+        key, rsa.RSAPublicKey | ec.EllipticCurvePublicKey | ed25519.Ed25519PublicKey | ed448.Ed448PublicKey
+    ):
+        return False
+    return crl.is_signature_valid(key)
+
+
+def _cutoff(now: datetime, *, within: timedelta | None, by: datetime | None, default: timedelta) -> datetime:
+    if within is not None and within < timedelta(0):
+        raise TinyPkiError(f"Expected a non-negative within, got {within}")
+    candidates: list[datetime] = []
+    if within is not None:
+        candidates.append(now + within)
+    if by is not None:
+        candidates.append(_require_aware(by, "by"))
+    return min(candidates) if candidates else now + default
+
+
+def _is_issued_by(cert: x509.Certificate, ca_cert: x509.Certificate) -> bool:
+    try:
+        cert.verify_directly_issued_by(ca_cert)
+    except (InvalidSignature, TypeError, ValueError):
+        return False
+    return True
+
+
+def _load_ca(ca_cert_pem: bytes) -> x509.Certificate:
+    """Load a trust anchor, rejecting certificates without ``BasicConstraints(ca=True)``."""
+    ca_cert = x509.load_pem_x509_certificate(ca_cert_pem)
+    try:
+        is_ca = ca_cert.extensions.get_extension_for_class(x509.BasicConstraints).value.ca
+    except x509.ExtensionNotFound:
+        is_ca = False
+    if not is_ca:
+        raise TinyPkiError(
+            f"Expected a CA certificate (BasicConstraints ca=True) for ca_cert_pem, got {_name_label(ca_cert.subject)}"
+        )
+    return ca_cert
+
+
+def _name_label(name: x509.Name) -> str:
+    cn_attrs = name.get_attributes_for_oid(NameOID.COMMON_NAME)
+    return str(cn_attrs[0].value) if cn_attrs else name.rfc4514_string()
+
+
+def _require_aware(value: datetime, field_name: str) -> datetime:
+    if value.tzinfo is None:
+        raise TinyPkiError(f"Expected a timezone-aware {field_name}, got naive {value.isoformat()}")
+    return value.astimezone(UTC)
+
+
+def _result(
+    *,
+    kind: CertificateKind,
+    subject: str,
+    issuer: str,
+    serial_number: int | None,
+    not_before: datetime,
+    not_after: datetime | None,
+    now: datetime,
+    cutoff: datetime,
+    reasons: list[tuple[Status, str]],
+) -> CertificateStatus:
+    status = max((s for s, _ in reasons), key=lambda s: s.severity, default=Status.OK)
+    days_remaining = None if not_after is None else math.floor((not_after - now) / timedelta(days=1))
+    return CertificateStatus(
+        kind=kind,
+        subject=subject,
+        issuer=issuer,
+        serial_number=serial_number,
+        not_before=not_before,
+        not_after=not_after,
+        cutoff=cutoff,
+        days_remaining=days_remaining,
+        status=status,
+        reasons=tuple(message for _, message in reasons),
+    )
+
+
+def _time_reasons(
+    now: datetime, not_before: datetime, not_after: datetime, cutoff: datetime
+) -> list[tuple[Status, str]]:
+    if now < not_before:
+        return [(Status.NOT_YET_VALID, f"not valid before {not_before.isoformat()}")]
+    if now >= not_after:
+        return [(Status.EXPIRED, f"expired on {not_after.isoformat()}")]
+    if not_after <= cutoff:
+        return [(Status.EXPIRING, f"expires on {not_after.isoformat()}, before the cutoff {cutoff.isoformat()}")]
+    return []

tiny_pki/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for tiny-pki (REPL + one-shot commands)."""