Decree.PersonalFields.Envelope (decree v0.1.0)

Copy Markdown View Source

The stored form of a personal value: a JSON object, never a string.

{"$pf": 1, "k": "<key_id>", "s": "<subject_id>", "n": "<nonce>", "c": "<ciphertext+tag>"}

An object can never be confused with the string a field held before, which a prefixed string could be for a field a person types into. $pf is the format version, and its presence is the shape test. A deserialized event body has atom keys and metadata string keys, so the test takes both. k names the data key, and s the subject, so that a read never has to work out the subject again. Both stay in clear, as a read needs them to find the key.

The primitive

AES-256-GCM through :crypto.crypto_one_time_aead/7, with a 16-byte tag. Each encryption takes a fresh random 12-byte nonce from :crypto.strong_rand_bytes/1. n and c are base64, and c is the ciphertext followed by the tag.

The plaintext is the value's JSON, so a value that is not a string keeps its type.

What the additional data binds

The additional data is "pf1", the key id, the stream, the event type and the field, joined with a NUL byte. So a value does not decrypt under another key, in another stream, in another event type, or in another field:

  • The stream is the source stream, RecordedEvent.stream_id, on every read.

  • The event type is the stored string, EventData.event_type and RecordedEvent.event_type, so it is unchanged by an upcaster. A snapshot's is the literal "snapshot".

  • The field is the field's name. A metadata entry's is "metadata.<key>", so a value can't move between body and metadata. A snapshot's is "<state_field>.<entry_key>" for a list entry and "<state_field>" for a scalar.

It does not bind the event id. Someone with write access to the store can copy a value between two events of the same type, stream and field, and it will decrypt.

It does not bind the subject either: s is checked by the key it leads to, whose id must equal k.

Summary

Types

Where a value is stored: its stream, its event type and its field.

t()

An envelope's parts, decoded.

Functions

Decrypts an envelope, answering :error when the key, the location or the bytes do not match.

Encrypts a value under key for the given location, with a fresh nonce.

Does this value have the envelope's shape? A map with $pf does, well formed or not.

The key id an envelope names.

Reads an envelope's parts. A map that has the shape and not the parts is :error, never a value: exactly $pf at this version, k, s, n and c, each decoding to its size.

The subject an envelope names.

Types

location()

@type location() ::
  {stream :: String.t(), event_type :: String.t(), field :: String.t()}

Where a value is stored: its stream, its event type and its field.

t()

@opaque t()

An envelope's parts, decoded.

Functions

decrypt(envelope, key, location)

@spec decrypt(t(), binary(), location()) :: {:ok, term()} | :error

Decrypts an envelope, answering :error when the key, the location or the bytes do not match.

encrypt(value, arg, subject_id, location)

@spec encrypt(term(), {String.t(), binary()}, String.t(), location()) ::
  {:ok, map()} | {:error, :personal_field_not_encodable}

Encrypts a value under key for the given location, with a fresh nonce.

Answers {:error, :personal_field_not_encodable} for a value with no JSON form, never a raise that could carry it.

envelope?(value)

@spec envelope?(term()) :: boolean()

Does this value have the envelope's shape? A map with $pf does, well formed or not.

key_id(map)

@spec key_id(t()) :: String.t()

The key id an envelope names.

parse(value)

@spec parse(map()) :: {:ok, t()} | :error

Reads an envelope's parts. A map that has the shape and not the parts is :error, never a value: exactly $pf at this version, k, s, n and c, each decoding to its size.

subject_id(map)

@spec subject_id(t()) :: String.t()

The subject an envelope names.