# `Decree.PersonalFields.Envelope`
[🔗](https://github.com/sparkle-space/decree/blob/v0.1.0/lib/decree/personal_fields/envelope.ex#L1)

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`.

# `location`

```elixir
@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`

```elixir
@opaque t()
```

An envelope's parts, decoded.

# `decrypt`

```elixir
@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`

```elixir
@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?`

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

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

# `key_id`

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

The key id an envelope names.

# `parse`

```elixir
@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`

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

The subject an envelope names.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
