Personal fields: values encrypted under their subject's key before they reach the store.
An event declares its personal fields and metadata entries, and whose they are, through
Decree.Event.PersonalFields. An application names where keys come from with key_source:
on use Decree.Application (see Decree.PersonalFields.KeySource). Nothing else is needed,
and an application or an event that declares nothing is unchanged.
The store only ever sees JSON: everything here runs in the framework.
What each path does
Append.
Decree.Event.Append.prepare/4looks up each subject of each event, drops erased values, takes the tags from the plaintext that will be stored, then encrypts. A retired slot takes no lookup and is stored as given, and an envelope in one fails the append with{:error, :personal_field_is_envelope}. A metadata key the application lists inpersonal_metadata_keys:passes only when the event declares it underpersonal_metadata:; retiring it is not enough. An aggregate's append runsprepare/4, and a decision's, once per member with that member's stream.Decree.EventStore.append_to_stream/5andDecree.Storedo not: an application's own direct append of a declared event stores what it is given, so a build check of its own must fence that.Delivery.
Decree.Event.Handlerdecrypts an event for a handler whosehandle/2names it in a clause head, and for no other, retired slots included. TheRecordedEventis never rewritten.Rehydration. An aggregate lists the events its state reads with
Decree.PersonalFields.Aggregate, and those are decrypted in its fold.Decisions. A
Decree.Decisionlists the events it reads the same way, and those reachevolve/2andfollowup_query/3decrypted, body only. Every other event reaches them as stored. There is no snapshot.Rules. A
Decree.Decision.Rulelists the events it reads the same way, and those reachfollowup_query/3andexecute/2decrypted, body only. See "Personal fields" there.Snapshots. The state an aggregate lists is encrypted on the way to the store and decrypted on the way back.
Stream reads. A bare read answers ciphertext. A reader that needs plaintext calls
decrypt_recorded_event/2.Upcasters run first, and see ciphertext. One may pass an envelope on, or move it to another struct. It can't read it, or move it to another field. The declaration read is the upcast struct's: a slot it neither declares nor retires reaches a reader as stored.
Every read path walks an event's retired slots after its declared ones, the same way.
Three answers
A lookup answers a key, :erased or :unknown. Erased means absent: a field is nil and a
metadata key is gone. Unknown is everything else, and it is never written or read as absent:
an append fails with {:error, :key_unknown}, a delivery is held and not acked, an
aggregate stops rather than fold a missing value, and a decision answers
{:error, :key_unknown} with nothing appended. See Decree.Event.Handler,
Decree.Aggregates.Aggregate and Decree.Decision.
A nil stays nil. A bare value in a declared field passes through, and emits
[:decree, :personal_field, :plaintext_read] unless its subject is {:when_present, _}. A
bare value in a retired slot passes through with no lookup and emits nothing.
Telemetry
[:decree, :personal_field, :key_unknown], with%{application:, subject_id:}, for a lookup that answered unknown and for a value that a key could not read.subject_idis nil for a malformed envelope or a subject that is not an id.[:decree, :personal_field, :plaintext_read], with%{application:, event_type:, field:}and no value.
Summary
Functions
Decrypts a recorded event for a reader that needs plaintext.
Types
Functions
@spec decrypt_recorded_event( Decree.Application.t(), Decree.EventStore.RecordedEvent.t() ) :: {:ok, Decree.EventStore.RecordedEvent.t()} | {:error, :key_unknown}
Decrypts a recorded event for a reader that needs plaintext.
Answers {:ok, event}, with its fields and metadata decrypted, erased fields nil and erased
metadata keys removed, or {:error, :key_unknown} if any value can't be read. An event that
declares nothing comes back as it is.
The declaration read is the one of the struct after upcasting, and the subject is each envelope's own, so a conditional declaration is not worked out again.