Helpers

Reveal helpers

Convenience helpers for backend consumers of the financial instrument reveal API.

These helpers wrap the full reveal lifecycle (key generation, registration, reveal, decryption) into single atomic function calls. The ephemeral RSA key pair is generated internally and never exposed to the caller.

Usage

from components.payment_gateway.public.parties import ( FinancialInstrumentRevealQueries, ) from components.payment_gateway.subcomponents.parties.protected.business_logic.reveal import ( backend_reveal_actor, reveal_iban_account_details, )

reveal_queries = FinancialInstrumentRevealQueries.create() details = reveal_iban_account_details( reveal_queries, session, financial_instrument_id, reason="legal_document_generation", actor=backend_reveal_actor("banking_documents"), )

components.payment_gateway.subcomponents.parties.protected.business_logic.reveal.backend_reveal_actor

backend_reveal_actor(component_name)

Build an actor string for backend component callers.

Parameters:

Name	Type	Description	Default
component_name	str	Name of the calling component (e.g. "banking_documents").	required

Returns:

Type	Description
str	Formatted actor string like "component:banking_documents".

Source code in components/payment_gateway/subcomponents/parties/protected/business_logic/reveal.py

def backend_reveal_actor(component_name: str) -> str:
    """Build an actor string for backend component callers.

    Args:
        component_name: Name of the calling component (e.g. "banking_documents").

    Returns:
        Formatted actor string like "component:banking_documents".
    """
    return f"component:{component_name}"

components.payment_gateway.subcomponents.parties.protected.business_logic.reveal.decrypt_reveal_jwe

decrypt_reveal_jwe(private_key_pem, jwe_token)

Decrypt a JWE token from a reveal operation and parse the JSON payload.

Parameters:

Name	Type	Description	Default
private_key_pem	str	RSA private key in PEM format.	required
jwe_token	str	JWE token string returned by a reveal method.	required

Returns:

Type	Description
dict	Parsed JSON payload as a dictionary.

Source code in components/payment_gateway/subcomponents/parties/protected/business_logic/reveal.py

def decrypt_reveal_jwe(private_key_pem: str, jwe_token: str) -> dict:  # type: ignore[type-arg]
    """Decrypt a JWE token from a reveal operation and parse the JSON payload.

    Args:
        private_key_pem: RSA private key in PEM format.
        jwe_token: JWE token string returned by a reveal method.

    Returns:
        Parsed JSON payload as a dictionary.
    """
    from shared.encryption.crypto_utils import decrypt_jwe_data

    payload_bytes = decrypt_jwe_data(private_key_pem, jwe_token)
    return json.loads(payload_bytes)  # type: ignore[no-any-return]

components.payment_gateway.subcomponents.parties.protected.business_logic.reveal.frontend_reveal_actor

frontend_reveal_actor(role, user_id)

Build an actor string for frontend callers (used in controllers).

Parameters:

Name	Type	Description	Default
role	str	User role (e.g. "member", "admin", "care").	required
user_id	str	User identifier.	required

Returns:

Type	Description
str	Formatted actor string like "member:{user_id}".

Source code in components/payment_gateway/subcomponents/parties/protected/business_logic/reveal.py

def frontend_reveal_actor(role: str, user_id: str) -> str:
    """Build an actor string for frontend callers (used in controllers).

    Args:
        role: User role (e.g. "member", "admin", "care").
        user_id: User identifier.

    Returns:
        Formatted actor string like "member:{user_id}".
    """
    return f"{role}:{user_id}"

components.payment_gateway.subcomponents.parties.protected.business_logic.reveal.generate_reveal_key_pair

generate_reveal_key_pair()

Generate an ephemeral RSA key pair for a reveal operation.

Returns:

Type	Description
tuple[str, str]	Tuple of (private_key_pem, public_key_pem) as strings.

Source code in components/payment_gateway/subcomponents/parties/protected/business_logic/reveal.py

def generate_reveal_key_pair() -> tuple[str, str]:
    """Generate an ephemeral RSA key pair for a reveal operation.

    Returns:
        Tuple of (private_key_pem, public_key_pem) as strings.
    """
    from cryptography.hazmat.primitives import serialization
    from cryptography.hazmat.primitives.asymmetric import rsa

    private_key = rsa.generate_private_key(
        public_exponent=65537,
        key_size=2048,
    )

    private_key_pem = private_key.private_bytes(
        encoding=serialization.Encoding.PEM,
        format=serialization.PrivateFormat.PKCS8,
        encryption_algorithm=serialization.NoEncryption(),
    ).decode("utf-8")

    public_key_pem = (
        private_key.public_key()
        .public_bytes(
            encoding=serialization.Encoding.PEM,
            format=serialization.PublicFormat.SubjectPublicKeyInfo,
        )
        .decode("utf-8")
    )

    return private_key_pem, public_key_pem

components.payment_gateway.subcomponents.parties.protected.business_logic.reveal.reveal_ca_local_account_details

reveal_ca_local_account_details(
    reveal_queries, session, /, id, *, reason, actor
)

Reveal Canadian local account details in a single atomic operation.

Generates an ephemeral RSA key pair, registers it, calls reveal, decrypts the JWE response, and returns the cleartext details. The private key never leaves this function.

Parameters:

Name	Type	Description	Default
reveal_queries	FinancialInstrumentRevealQueries	FinancialInstrumentRevealQueries instance.	required
session	Session	Database session.	required
id	FinancialInstrumentId	Financial instrument ID.	required
reason	str	Why the reveal is needed (free-form, non-empty).	required
actor	str	Who is requesting the reveal (use backend_actor() helper).	required

Returns:

Type	Description
CALocalAccountDetails	CALocalAccountDetails with the full Canadian local account data.

Source code in components/payment_gateway/subcomponents/parties/protected/business_logic/reveal.py

def reveal_ca_local_account_details(
    reveal_queries: FinancialInstrumentRevealQueries,
    session: Session,
    /,
    id: FinancialInstrumentId,
    *,
    reason: str,
    actor: str,
) -> CALocalAccountDetails:
    """Reveal Canadian local account details in a single atomic operation.

    Generates an ephemeral RSA key pair, registers it, calls reveal,
    decrypts the JWE response, and returns the cleartext details.
    The private key never leaves this function.

    Args:
        reveal_queries: FinancialInstrumentRevealQueries instance.
        session: Database session.
        id: Financial instrument ID.
        reason: Why the reveal is needed (free-form, non-empty).
        actor: Who is requesting the reveal (use backend_actor() helper).

    Returns:
        CALocalAccountDetails with the full Canadian local account data.
    """
    private_key_pem, public_key_pem = generate_reveal_key_pair()

    reveal_key_id = reveal_queries.register_reveal_key(
        public_key_pem,
        reason=reason,
        actor=actor,
    )

    jwe_token = reveal_queries.reveal_ca_local_account_details(
        session,
        id=id,
        reveal_key_id=reveal_key_id,
    )

    payload = decrypt_reveal_jwe(private_key_pem, jwe_token)
    return CALocalAccountDetails.from_dict(payload)

components.payment_gateway.subcomponents.parties.protected.business_logic.reveal.reveal_iban_account_details

reveal_iban_account_details(
    reveal_queries, session, /, id, *, reason, actor
)

Reveal IBAN account details in a single atomic operation.

Generates an ephemeral RSA key pair, registers it, calls reveal, decrypts the JWE response, and returns the cleartext details. The private key never leaves this function.

Parameters:

Name	Type	Description	Default
reveal_queries	FinancialInstrumentRevealQueries	FinancialInstrumentRevealQueries instance.	required
session	Session	Database session.	required
id	FinancialInstrumentId	Financial instrument ID.	required
reason	str	Why the reveal is needed (free-form, non-empty).	required
actor	str	Who is requesting the reveal (use backend_actor() helper).	required

Returns:

Type	Description
IBANAccountDetails	IBANAccountDetails with the full IBAN account data.

Source code in components/payment_gateway/subcomponents/parties/protected/business_logic/reveal.py

def reveal_iban_account_details(
    reveal_queries: FinancialInstrumentRevealQueries,
    session: Session,
    /,
    id: FinancialInstrumentId,
    *,
    reason: str,
    actor: str,
) -> IBANAccountDetails:
    """Reveal IBAN account details in a single atomic operation.

    Generates an ephemeral RSA key pair, registers it, calls reveal,
    decrypts the JWE response, and returns the cleartext details.
    The private key never leaves this function.

    Args:
        reveal_queries: FinancialInstrumentRevealQueries instance.
        session: Database session.
        id: Financial instrument ID.
        reason: Why the reveal is needed (free-form, non-empty).
        actor: Who is requesting the reveal (use backend_actor() helper).

    Returns:
        IBANAccountDetails with the full IBAN account data.
    """
    private_key_pem, public_key_pem = generate_reveal_key_pair()

    reveal_key_id = reveal_queries.register_reveal_key(
        public_key_pem,
        reason=reason,
        actor=actor,
    )

    jwe_token = reveal_queries.reveal_iban_account_details(
        session,
        id=id,
        reveal_key_id=reveal_key_id,
    )

    payload = decrypt_reveal_jwe(private_key_pem, jwe_token)
    return IBANAccountDetails.from_dict(payload)