tiny_ca.db.base_db module

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

SRPBaseDB declares what the registry must be able to do; concrete

subclasses decide how.

OCPNew query operations are added by extending BaseDB; existing

implementations are not modified.

LSPEvery concrete subclass must honour the documented pre- and post-conditions

of each method so callers can substitute implementations freely.

ISPThe interface is intentionally narrow — only operations that callers

actually need are declared here.

DIPHigh-level modules (e.g. CertLifecycleManager) depend on BaseDB,

never on SyncDBHandler or any other concrete implementation.

class tiny_ca.db.base_db.BaseDB

Bases: 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 delete_by_uuid(uuid)

Permanently delete the certificate record identified by uuid.

This is a hard delete — the row is removed from the database. The caller is responsible for also removing the corresponding filesystem artefacts via BaseStorage.delete_certificate_folder.

Parameters:

uuid (str) – The storage folder UUID that uniquely identifies the certificate.

Returns:

True if a row was found and deleted; False if no matching record existed or if a database error occurred.

Return type:

bool

abstractmethod get_by_name(common_name)

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:

The active VALID record for common_name, or None if no such record exists.

Return type:

CertificateRecord | None

abstractmethod get_by_serial(serial)

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:

The matching record regardless of its current status (VALID, REVOKED, EXPIRED), or None if no record exists for serial.

Return type:

CertificateRecord | None

abstractmethod get_expiring(within_days=30)

Return VALID certificates that expire within within_days calendar days.

Only records with status == VALID are considered — already-revoked or expired records are excluded.

Parameters:

within_days (int) – Look-ahead window in calendar days. Default: 30.

Returns:

Records ordered by not_valid_after ascending (soonest first). Returns an empty list on error.

Return type:

list[CertificateRecord]

abstractmethod get_revoked_certificates()

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.

Return type:

Generator[CertificateRecord, None, None]

abstractmethod list_all(status=None, key_type=None, limit=100, offset=0)

Return a paginated list of certificate records with optional filters.

Parameters:

• status (str | None) – Filter by lifecycle state ("valid", "revoked", "expired"). None returns all statuses.

• key_type (str | None) – Filter by certificate category ("ca", "service", "device", etc.). None returns all types.

• limit (int) – Maximum number of records to return. Default: 100.

• offset (int) – Number of records to skip (for pagination). Default: 0.

Returns:

Matching records ordered by id descending (newest first). Returns an empty list on error.

Return type:

list[CertificateRecord]

abstractmethod register_cert_in_db(cert, uuid, key_type=CertType.DEVICE)

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:

True if the record was persisted successfully; False if the operation failed (the implementation must log the reason and roll back any partial changes).

Return type:

bool

abstractmethod revoke_certificate(serial_number, reason=<ReasonFlags.unspecified: 'unspecified'>)

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:

(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).

Return type:

tuple[bool, object]

abstractmethod update_status_expired()

Bulk-update all VALID certificates whose not_valid_after has passed.

Sets status = "expired" for every record where: - status == "valid" - not_valid_after < now (UTC)

This method is intended to be called periodically by a background task (e.g. a cron job or an APScheduler job) so that status queries reflect reality without per-request date comparisons.

Returns:

Number of rows updated. Returns 0 on error (after logging).

Return type:

int