Field Encryption Utilities
Component Detail
Description
Utility layer providing decryption of sensitive contact fields stored encrypted in Supabase. Handles key retrieval, decryption logic, and error handling for missing or expired keys.
field-encryption-utils
Summaries
Field Encryption Utilities protect the organization's most sensitive member data by ensuring that personal information stored in encrypted form is only ever exposed to authorized users, and even then only in a controlled, auditable way. When encryption keys are missing or expired, the component automatically falls back to masked display rather than exposing raw encrypted strings or crashing — this graceful degradation protects both data integrity and user trust. For an organization handling personal data of individuals with visual impairments, this level of data protection is not just a technical detail; it is a legal and ethical obligation that directly affects organizational reputation and regulatory compliance.
Field Encryption Utilities is the highest-complexity component in this batch, and its delivery timeline should reflect that. Key management — how encryption keys are provisioned, rotated, and retrieved at runtime — must be fully specified before implementation begins, as ambiguity here is the most common cause of delays in encryption-related work. Testing needs to cover at least four scenarios: successful decryption, decryption with an expired key, decryption with a missing key, and integrity verification failure. Since this utility is consumed by the contact detail view, its stability is a hard prerequisite for completing the encrypted-field display feature.
Identify the key storage mechanism and access control rules as early blockers and get them resolved in the first sprint.
Field Encryption Utilities provides three methods: decryptField takes an encrypted string and a key reference identifier, retrieves the corresponding key, and returns the plaintext value; isDecryptable performs a pre-check to determine whether a given encrypted value can be successfully decrypted before attempting it (useful for conditional UI rendering); maskFieldValue returns a redacted display string for a given field key when decryption is not possible. The component must handle key retrieval failures (network errors, missing keys, expired keys) without throwing unhandled exceptions — all error paths should resolve to either a masked value or a typed error result consumed by the caller. Encryption algorithm and key storage backend (e.g., secure enclave, keychain, remote KMS) must be decided at the architecture level before implementing this utility, as those decisions directly shape the implementation of decryptField.
Responsibilities
- Decrypt encrypted field values using organization-specific keys
- Handle decryption errors gracefully with masked fallback display
- Verify field integrity after decryption
Interfaces
decryptField(String encryptedValue, String keyRef) -> String
isDecryptable(String encryptedValue) -> bool
maskFieldValue(String fieldKey) -> String
Relationships
Dependents (2)
Components that depend on this component