cadrumo.application.modelo.review_package_recipient_registry module

Recipient fingerprint registry for review-package recipient encryption.

This module lets a taxpayer record who they trust to receive an encrypted review package – an accountant or gestor – by the SHA-256 fingerprint of that recipient’s X25519 public key, verified out-of-band (read aloud, compared over a separate channel) before it is trusted. It is the taxpayer-side companion to review_package_recipient_encryption, which consumes a registered recipient’s public key to seal a review package so only that recipient’s matching private key can open it.

This registry never stores a private key of any kind: it is exclusively a record of OTHER PEOPLE’s public keys, mirroring how a real address book of trusted correspondents works. The taxpayer’s own encryption keypair (needed only for a future reverse flow, where an accountant encrypts feedback back to the taxpayer) is out of scope for this module.

Persistence is supplied through a required application-owned registry capability. The outward adapter binds that capability to one FINANCIAL-sensitivity secure-object singleton per bucket, returning an empty register when absent. Duplicate-recipient_id refusal remains application policy, and the registry stores public-key trust records only, never private key material.

See also

review_package_recipient_encryption

Consumes a registered recipient’s public key to encrypt a review package.

review_package_signing

Sibling per-profile keypair primitive (Ed25519, signature-only) this module’s X25519 keypair concept deliberately does not share key material with – signing and encryption keys must not be reused across purposes.

RecipientFingerprintRegistryPorts

Required persistence capability supplied by composition.

exception RecipientFingerprintRegistryError(message=None, *, context=None, translated_message=None)[source]

Bases: CadrumoError

Base error for recipient-fingerprint registry failures.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
exception RecipientAlreadyRegisteredError(message=None, *, context=None, translated_message=None)[source]

Bases: RecipientFingerprintRegistryError

Raised when add is called with a recipient_id already on file.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
exception RecipientNotRegisteredError(message=None, *, context=None, translated_message=None)[source]

Bases: RecipientFingerprintRegistryError

Raised when remove or a lookup names a recipient_id not on file.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
class RecipientFingerprintRecord(**data)[source]

Bases: BaseModel

One trusted recipient’s public encryption key on file.

public_key_hex is the recipient’s raw 32-byte X25519 public key (RFC 7748), hex-encoded. fingerprint_sha256 is a plain (non- persisted) property – SHA-256 of the raw public key bytes, hex-encoded – so it can never drift from the key it fingerprints and never needs to round-trip through the strict-extra-forbid persistence boundary; it exists purely for a human-readable out-of-band verification string (the taxpayer reads it aloud to / compares it against a value the accountant reads from their own key export).

Parameters:

data (Any)

recipient_id: str
label: str
public_key_hex: str
added_at: datetime
property fingerprint_sha256: str

SHA-256 hex digest of the raw public key bytes, for out-of-band display.

public_key()[source]

Reconstruct the live X25519PublicKey from stored raw bytes.

Return type:

X25519PublicKey

class RecipientFingerprintRegister(**data)[source]

Bases: BaseModel

A bucket’s full set of trusted recipient fingerprint records.

recipient_id is the register’s natural key: the application lookup service resolves a recipient by it, and the resolved record supplies the public key a package is sealed to.

Parameters:

data (Any)

records: tuple[RecipientFingerprintRecord, ...]
public_key_hex_from_raw_bytes(raw_public_key)[source]

Validate and hex-encode a raw X25519 public key.

Parameters:

raw_public_key (bytes) – Exactly 32 raw bytes (RFC 7748 encoding).

Raises:

RecipientFingerprintRegistryError – If raw_public_key is not exactly 32 bytes, or is not a well-formed X25519 point.

Return type:

str

list_recipient_fingerprints(*, ports)[source]

Return every trusted recipient through the required registry capability.

Return type:

tuple[RecipientFingerprintRecord, ...]

Parameters:

ports (RecipientFingerprintRegistryPorts)

get_recipient_fingerprint(recipient_id, *, ports)[source]

Resolve one trusted recipient or raise the application lookup refusal.

Return type:

RecipientFingerprintRecord

Parameters:
add_recipient_fingerprint(*, recipient_id, public_key_hex, ports, label='', added_at=None)[source]

Add a trusted recipient, refusing duplicate ids before persistence.

Return type:

RecipientFingerprintRegister

Parameters:
remove_recipient_fingerprint(recipient_id, *, ports)[source]

Remove one trusted recipient, refusing an unknown id.

Return type:

RecipientFingerprintRegister

Parameters: