common.blindfold

Blindfold encryption utilities for SecretVaults API.

class BlindfoldOperation(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Valid blindfold operations.

STORE = 'store'

MATCH = 'match'

SUM = 'sum'

__new__(value)

__repr__()

Return repr(self).

__str__()

Return str(self).

__format__(format_spec)

Return a formatted version of the string as described by format_spec.

class BlindfoldFactoryConfig(key: SecretKey | ClusterKey | None = None, operation: BlindfoldOperation | None = None, seed: bytes | str | None = None, use_cluster_key: bool | None = None, threshold: int | None = None)

Bases: object

Defines valid configurations for creating or using a Blindfold encryption key.

This class represents the union type from TypeScript with different scenarios: - Scenario 1: Use a pre-existing key - Scenario 2: Generate a SecretKey (allows seed) - Scenario 3: Generate a ClusterKey (disallows seed)

async to_blindfold_key(options: BlindfoldFactoryConfig, cluster_size: int) → SecretKey | ClusterKey

Create a blindfold key based on the provided configuration.

Parameters:

• options – Configuration for key creation

• cluster_size – Number of nodes in the cluster

Returns:

SecretKey or ClusterKey based on configuration

async encrypt(key: SecretKey | ClusterKey, plaintext: int | str | bytes) → str | List[str] | List[int] | List[List[int]]

Encrypt a plaintext value using the blindfold library.

Parameters:

• key – SecretKey or ClusterKey for encryption

• plaintext – Value to encrypt

Returns:

Encrypted value

async conceal(key: SecretKey | ClusterKey, data: Dict[str, Any]) → List[Dict[str, Any]]

Encrypts fields marked with %allot and then splits the object into an array of secret shares.

Parameters:

• key – SecretKey or ClusterKey for encryption

• data – Data to conceal with fields marked with %allot

Returns:

Array of secret shares, one per node

Example

data = [{
    "patientId": {"%allot": "user-123"},  # This value will be concealed
    "visitDate": "2025-06-24",            # This value will remain public
}]

# Output assuming 2 nodes:
[
    # Document to be stored on Node 1
    {
        "patientId": {"%share": "<ciphertext_a_for_user-123>"},
        "visitDate": "2025-06-24",
    },
    # Document to be stored on Node 2
    {
        "patientId": {"%share": "<ciphertext_b_for_user-123>"},
        "visitDate": "2025-06-24",
    },
]

async unify(key: SecretKey | ClusterKey, shares: List[Dict[str, Any]]) → Dict[str, Any]

Recombines an array of secret shares and decrypts the concealed values to restore the original object.

Parameters:

• key – SecretKey or ClusterKey for decryption

• shares – Array of secret shares from different nodes

Returns:

Original data with concealed values revealed

async reveal(key: SecretKey | ClusterKey, shares: List[Dict[str, Any]]) → Dict[str, Any]

Recombines an array of secret shares and decrypts the concealed values to restore the original object.

Parameters:

• key – SecretKey or ClusterKey for decryption

• shares – Array of secret shares from different nodes

Returns:

Original data with concealed values revealed

Example

shares = [
    {
        "patientId": {"%share": "<ciphertext_A_for_user-123>"},
        "visitDate": "2025-06-24",
    },
    {
        "patientId": {"%share": "<ciphertext_B_for_user-123>"},
        "visitDate": "2025-06-24",
    },
]

# Output:
{
    "patientId": "user-123",
    "visitDate": "2025-06-24",
}