@callback exec(wrapper :: t(), (sensitive_data -> result), exec_opts()) :: result
when sensitive_data: term(), result: term()

Returns the result of the callback invoked with the sensitive term.

Executes the provided function with the sensitive term provided as the function argument, ensuring no data leaks in case of error.

The unwrapped result of the callback execution is then either returned as is, or wrapped according to provided options.

Options

See exec_opts/0.

Examples

# CreditCard implements the SensitiveData.Wrapper behaviour
credit_card = CreditCard.from(fn -> "5105105105105100" end)

# We can call a function that expect a credit card number (in string
# format), and will return `%{result: :ok}` upon successful payment:
%{result: :ok} = CreditCard.exec(credit_card, &pay_with_credit_card/1)

# We can also alter the wrapped data without ever exposing it outside
# of a sensitive context protecting the data from leaks:
# PaymentToken implements the SensitiveData.Wrapper behaviour
CreditCard.exec(credit_card, fn card_number -> tokenize(card_number) end, into: PaymentToken)
# #PaymentToken<...>

@callback from(function(), wrap_opts()) :: t()

Wraps the sensitive term returned by the callback to prevent unwanted data leaks.

The callback is executed only once: during wrapper instanciation.

Options

See wrap_opts/0.

Examples

MySensitiveData.from(fn -> "foo" end)
# #MySensitiveData<...>

MySensitiveData.from(fn -> "5105105105105100" end, label: :credit_card_user_bob)
# #MySensitiveData<label: :credit_card_user_bob, ...>

@callback map(
  wrapper :: t(),
  (sensitive_data_orig -> sensitive_data_transformed),
  wrap_opts()
) :: t()
when sensitive_data_orig: term(), sensitive_data_transformed: term()

Invokes the callback on the wrapped sensitive term and returns the wrapped result.

Options

See wrap_opts/0.

Examples

data = MySensitiveData.from(fn -> "foo" end)

MySensitiveData.map(data, fn orig -> orig <> "bar" end, label: :now_foobar)
# #MySensitiveData<label: :now_foobar, ...>

@callback unwrap(wrapper :: t()) :: term()

Returns the sensitive term within wrapper.

By default, this optional callback will not be generated when SensitiveData.Wrapper is used.

Avoid Unwrapping Sensitive Data

Calling this function should be discouraged: exec/3 should be used instead to interact with sensitive data.

You can always obtain the raw sensitive data via exec(wrapped_value, & &1) but should seriously reconsider if that's needed: usually a combination of map/2 and exec/2 should satisfy all your needs regarding sensitive data interaction, and sensitive data typically never needs to be extracted from wrappers.

Examples

data = MySensitiveData.from(fn -> "foo" end)

# Not recommended
MySensitiveData.unwrap(data)
# "foo"

# Do this instead if you absolutely must unwrap the value
MySensitiveData.exec(data, & &1)
# "foo"

@callback wrap(term(), wrap_opts()) :: t()

Wraps the sensitive term to prevent unwanted data leaks.

Prefer Using From

Calling this function should be discouraged: from/2 should be used instead to wrap sensitive data, as in all cases where you would call wrap(my_value) you should instead call from(fn -> my_value end).

The reason for this preference for from/2 is that it is much harder to accidentally misuse. For example, wrap(get_credit_card_number()) and from(get_credit_card_number) look very similar, but if get_credit_card_number/0 raises and leaks sensitive data when it does, the call to wrap/1 will raise and expose sensitive information whereas the call to from/1 will not. This is because from/2 internally wraps callback execution within SensitiveData.exec/2.

Additionally, making use of wrap/2 means you have access to unwrapped sensitive data, which should be discouraged: regardless of whether this sensitive data was fetched, generated, or derived, this should be done via functions from this library. Put another way, obtaining sensitive data and only then stuffing it into a wrapper is an anti-pattern that shouldn't be encouraged, and wrap/2 facilitates it.

Options

See wrap_opts/0

Examples

# Not recommended
MySensitiveData.wrap("foo")
# #MySensitiveData<...>

# Do this instead
MySensitiveData.from(fn -> "foo" end)
# #MySensitiveData<...>

# Not recommended
MySensitiveData.wrap("5105105105105100", label: :credit_card_user_bob)
# #MySensitiveData<label: :credit_card_user_bob, ...>

# Do this instead
MySensitiveData.from(fn -> "5105105105105100" end, label: :credit_card_user_bob)
# #MySensitiveData<label: :credit_card_user_bob, ...>