tiny-ca 0.1.0__py3-none-any.whl

tiny_ca/db/base_db.py

@@ -0,0 +1,173 @@
+"""
+
+Abstract base class that defines the contract for all certificate registry
+database adapters.
+
+Any class that inherits from ``BaseDB`` and implements all six abstract methods
+can be used wherever the application expects a database layer, without requiring
+any changes to the calling code (LSP / DIP).
+
+SOLID notes
+-----------
+SRP : ``BaseDB`` declares *what* the registry must be able to do; concrete
+      subclasses decide *how*.
+OCP : New query operations are added by extending ``BaseDB``; existing
+      implementations are not modified.
+LSP : Every concrete subclass must honour the documented pre- and post-conditions
+      of each method so callers can substitute implementations freely.
+ISP : The interface is intentionally narrow — only operations that callers
+      actually need are declared here.
+DIP : High-level modules (e.g. ``CertLifecycleManager``) depend on ``BaseDB``,
+      never on ``SyncDBHandler`` or any other concrete implementation.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Generator
+
+from cryptography import x509
+
+from tiny_ca.const import CertType
+
+from .models import CertificateRecord
+
+
+class BaseDB(ABC):
+    """
+    Abstract contract for the certificate registry database adapter.
+
+    Defines all operations that the application layer requires from the
+    persistence tier.  Concrete implementations (e.g. ``SyncDBHandler``)
+    provide the actual SQL queries and transaction management.
+
+    All methods that return a ``CertificateRecord`` must return ``None``
+    (not raise an exception) when the requested record simply does not exist.
+    Exceptions are reserved for genuine infrastructure failures (connection
+    errors, constraint violations, etc.).
+    """
+
+    @abstractmethod
+    def get_by_serial(self, serial: int) -> CertificateRecord | None:
+        """
+        Retrieve a certificate record by its X.509 serial number.
+
+        Parameters
+        ----------
+        serial : int
+            Integer serial number to look up.  Implementations are responsible
+            for any type conversion required by the underlying storage format
+            (e.g. converting to ``str`` for string-typed database columns).
+
+        Returns
+        -------
+        CertificateRecord | None
+            The matching record regardless of its current status (VALID,
+            REVOKED, EXPIRED), or ``None`` if no record exists for *serial*.
+        """
+
+    @abstractmethod
+    def get_by_name(self, common_name: str) -> CertificateRecord | None:
+        """
+        Retrieve the currently active certificate record for a given Common Name.
+
+        Implementations must filter to only ``VALID`` records so that the
+        caller always receives the live certificate or ``None`` — never a
+        revoked or expired one.
+
+        Parameters
+        ----------
+        common_name : str
+            The CN (Common Name) field from the certificate Subject to look up.
+
+        Returns
+        -------
+        CertificateRecord | None
+            The active VALID record for *common_name*, or ``None`` if no such
+            record exists.
+        """
+
+    @abstractmethod
+    def register_cert_in_db(
+        self,
+        cert: x509.Certificate,
+        uuid: str,
+        key_type: CertType = CertType.DEVICE,
+    ) -> bool:
+        """
+        Persist a newly issued certificate to the registry.
+
+        Creates a new record with ``status=VALID`` populated from the
+        certificate metadata.  The implementation must extract the CN from
+        ``cert.subject`` and store the full PEM encoding for later retrieval.
+
+        Parameters
+        ----------
+        cert : x509.Certificate
+            The issued X.509 certificate object to register.
+        uuid : str
+            UUID that identifies the filesystem folder containing the
+            corresponding ``.pem``, ``.key``, and ``.csr`` artefact files.
+        key_type : CertType
+            Certificate category (CA, USER, SERVICE, DEVICE, INTERNAL).
+            Default: ``CertType.DEVICE``.
+
+        Returns
+        -------
+        bool
+            ``True`` if the record was persisted successfully;
+            ``False`` if the operation failed (the implementation must log
+            the reason and roll back any partial changes).
+        """
+
+    @abstractmethod
+    def revoke_certificate(
+        self,
+        serial_number: int,
+        reason: x509.ReasonFlags = x509.ReasonFlags.unspecified,
+    ) -> tuple[bool, object]:
+        """
+        Mark a certificate as revoked and record the reason and timestamp.
+
+        Implementations must:
+        1. Look up the record by *serial_number* filtered to ``status=VALID``.
+        2. If not found, return ``(False, <NOT_FOUND status>)`` without error.
+        3. Update ``status``, ``revocation_reason``, and ``revocation_date``.
+        4. Commit atomically; roll back on any exception.
+
+        Parameters
+        ----------
+        serial_number : int
+            Serial number of the certificate to revoke.
+        reason : x509.ReasonFlags
+            RFC 5280 §5.3.1 revocation reason code.
+            Default: ``x509.ReasonFlags.unspecified`` (code 0).
+
+        Returns
+        -------
+        tuple[bool, object]
+            ``(success, status_value)`` where *status_value* is implementation-
+            defined (typically a ``RevokeStatus`` enum member).
+            ``True`` indicates the revocation was committed; ``False`` means it
+            was not (reason encoded in *status_value*).
+        """
+
+    @abstractmethod
+    def get_revoked_certificates(self) -> Generator[CertificateRecord, None, None]:
+        """
+        Yield certificate records that should appear in the current CRL.
+
+        Implementations define their own freshness window (e.g. only records
+        revoked within the past 365 days and not yet expired), but must yield
+        objects that expose at minimum:
+
+        - ``serial_number`` — castable to ``int``
+        - ``revocation_date`` — a ``datetime`` object
+        - ``revocation_reason`` — an integer RFC 5280 reason code
+
+        Yields
+        ------
+        CertificateRecord
+            Records (or row-like objects) for each revoked certificate that
+            falls within the implementation's CRL inclusion window.
+        """

tiny_ca/db/const.py

@@ -0,0 +1,92 @@
+"""
+db/const.py
+
+Shared constants for the database layer.
+
+Currently exports ``RevokeStatus``, the value object that encodes the
+possible outcomes of a certificate revocation attempt.  Keeping it in a
+dedicated module prevents circular imports between ``base_db``, the ORM
+models, and the concrete handler implementations.
+"""
+
+from __future__ import annotations
+
+from enum import Enum, StrEnum
+
+
+class RevokeStatus(Enum):
+    """
+    Enumerated outcomes for a certificate revocation attempt.
+
+    Used as the second element of the ``(bool, RevokeStatus)`` tuple returned
+    by ``BaseDB.revoke_certificate`` implementations.  The boolean indicates
+    overall success; this enum provides the machine-readable reason when the
+    operation did not succeed, and a confirmation token when it did.
+
+    Members
+    -------
+    NOT_FOUND :
+        No active (``VALID``) certificate with the requested serial number
+        exists in the registry.  The certificate may already be revoked,
+        expired, or was never registered.
+    UNKNOWN_ERROR :
+        An unexpected internal error (e.g. database constraint violation,
+        connection failure) prevented the revocation.  The implementation must
+        log the underlying exception before returning this status.
+    OK :
+        The revocation was committed successfully.  The certificate record has
+        been updated with ``status=REVOKED``, a ``revocation_date``, and the
+        provided ``revocation_reason``.
+
+    Examples
+    --------
+    >>> success, status = db.revoke_certificate(serial=12345, reason=ReasonFlags.key_compromise)
+    >>> if not success:
+    ...     if status == RevokeStatus.NOT_FOUND:
+    ...         logger.warning("Certificate not found")
+    ...     else:
+    ...         logger.error("Internal revocation error")
+    """
+
+    NOT_FOUND = (
+        "The certificate was not revoked because there is no valid certificate "
+        "with the specified serial number."
+    )
+    UNKNOWN_ERROR = (
+        "The certificate was not revoked due to an internal error. "
+        "Please review the service logs."
+    )
+    OK = "success"
+
+
+class CertificateStatus(StrEnum):
+    """
+    Lifecycle state of a certificate record in the registry.
+
+    Stored as a lowercase string in the ``status`` column of
+    ``CertificateRecord`` so the value is human-readable in raw SQL output.
+
+    Members
+    -------
+    VALID :
+        The certificate was issued successfully and has not been revoked or
+        expired.  Active certificates used for authentication or encryption
+        are expected to be in this state.
+    REVOKED :
+        The certificate was explicitly revoked before its natural expiry.
+        The ``revocation_date`` and ``revocation_reason`` columns on the
+        corresponding ``CertificateRecord`` row must be non-null.
+    EXPIRED :
+        The certificate's ``not_valid_after`` date has passed.  This status
+        may be set by a background job; alternatively, callers can detect
+        expiry by comparing ``not_valid_after`` to the current time.
+    UNKNOWN :
+        The status could not be determined, typically because no record was
+        found for the requested serial number.  Used as a safe sentinel value
+        by ``CertLifecycleManager.get_certificate_status``.
+    """
+
+    VALID = "valid"
+    REVOKED = "revoked"
+    EXPIRED = "expired"
+    UNKNOWN = "unknown"

tiny_ca/db/models.py

@@ -0,0 +1,144 @@
+"""
+
+SQLAlchemy ORM models and status enumerations for the certificate registry.
+
+Module-level contents
+---------------------
+``CertificateStatus``  — ``StrEnum`` representing the lifecycle state of a
+                         certificate row.
+``CertificateRecord``  — ORM-mapped table that stores all metadata for issued,
+                         revoked, and expired certificates.
+
+Design notes
+------------
+- ``CertificateStatus`` uses ``StrEnum`` so that values are stored as plain
+  strings in the database, making the column human-readable and compatible
+  with non-Python tooling that queries the database directly.
+- ``CertificateRecord`` stores the full PEM-encoded public certificate so the
+  certificate can be reconstructed independently of the filesystem artefacts.
+- ``serial_number`` is stored as ``String`` (not ``Integer``) because X.509
+  serial numbers can be up to 20 bytes / 160 bits, exceeding the range of a
+  64-bit SQL integer on most backends.
+- ``uuid`` links the database record to the filesystem folder managed by
+  ``BaseStorage``, enabling clean deletion of both the DB row and the
+  corresponding files together.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import Column, DateTime, Integer, String
+from sqlalchemy.orm import Mapped, declarative_base
+
+from tiny_ca.const import CertType
+
+from .const import CertificateStatus
+
+Base = declarative_base()
+
+
+class CertificateRecord(Base):  # type: ignore
+    """
+    ORM model for a single certificate entry in the registry.
+
+    Maps to the ``certificates`` table.  Each row represents one certificate
+    that has been issued by the CA, regardless of its current lifecycle state.
+
+    Columns
+    -------
+    id : int
+        Auto-incremented surrogate primary key.  Not exposed to application
+        code; use ``serial_number`` as the business key.
+    serial_number : str
+        X.509 serial number stored as a decimal string.  Unique and indexed.
+        String storage avoids integer overflow for 160-bit serials (RFC 5280).
+    common_name : str
+        Common Name (CN) extracted from the certificate Subject at issuance
+        time.  Not unique; the same CN may appear across different certificate
+        generations (e.g. after rotation).
+    status : str
+        Current lifecycle state.  One of the ``CertificateStatus`` values:
+        ``"valid"``, ``"revoked"``, ``"expired"``, or ``"unknown"``.
+        Defaults to ``CertificateStatus.VALID`` on insertion.
+    not_valid_before : datetime
+        Start of the certificate's validity period (UTC, naive datetime as
+        stored by SQLAlchemy's ``DateTime`` column type).
+    not_valid_after : datetime
+        End of the certificate's validity period (UTC, naive datetime).
+        Indexed to allow efficient queries for expired certificates.
+    key_type : str
+        Certificate category stored as the ``CertType`` enum's string value
+        (e.g. ``"ca"``, ``"device"``, ``"service"``).
+        Defaults to ``CertType.DEVICE.value``.
+    certificate_pem : str
+        Full PEM-encoded public certificate.  Allows reconstruction of the
+        ``x509.Certificate`` object without accessing the filesystem.
+    revocation_date : datetime | None
+        UTC timestamp at which the certificate was revoked.  ``None`` for
+        non-revoked certificates.
+    revocation_reason : int | None
+        RFC 5280 §5.3.1 revocation reason code stored as an integer.
+        ``None`` for non-revoked certificates.  Maps to the integer value
+        of the corresponding ``x509.ReasonFlags`` member.
+    uuid : str | None
+        UUID string that identifies the filesystem folder (managed by
+        ``BaseStorage``) holding the ``.pem``, ``.key``, and ``.csr`` files
+        for this certificate.  ``None`` if no filesystem artefacts exist.
+    """
+
+    __tablename__ = "certificates"
+
+    id = Column(Integer, primary_key=True)
+
+    serial_number = Column(
+        String,
+        unique=True,
+        nullable=False,
+        index=True,
+        comment="X.509 serial number as a decimal string (up to 160-bit value).",
+    )
+    common_name = Column(
+        String,
+        nullable=False,
+        comment="CN extracted from the certificate Subject at issuance time.",
+    )
+    status: Mapped[str] = Column(  # type: ignore
+        String,
+        default=CertificateStatus.VALID,
+        comment="Lifecycle state: valid | revoked | expired | unknown.",
+    )
+    not_valid_before = Column(
+        DateTime,
+        nullable=False,
+        comment="Start of the certificate validity window (UTC).",
+    )
+    not_valid_after = Column(
+        DateTime,
+        nullable=False,
+        index=True,
+        comment="End of the certificate validity window (UTC). Indexed for expiry queries.",
+    )
+    key_type = Column(
+        String,
+        default=CertType.DEVICE.value,
+        comment="Certificate category: ca | device | service | user | internal.",
+    )
+    certificate_pem = Column(
+        String,
+        nullable=False,
+        comment="Full PEM-encoded public certificate for offline reconstruction.",
+    )
+    revocation_date = Column(
+        DateTime,
+        nullable=True,
+        comment="UTC timestamp of revocation. NULL for non-revoked certificates.",
+    )
+    revocation_reason: Mapped[str] = Column(  # type: ignore
+        String,
+        nullable=True,
+        comment="RFC 5280 §5.3.1 reason code integer. NULL for non-revoked certificates.",
+    )
+    uuid = Column(
+        String,
+        unique=True,
+        comment="Filesystem folder UUID linking this record to its storage artefacts.",
+    )