Chronicle compliance and personal data
Chronicle keeps events forever, so personal data cannot be deleted from the log. Chronicle protects it by encrypting each marked value under a key owned by the subject, and erases it by destroying that key. Decide the subject before you decide the event shape — the subject is what erasure operates on.
Verified product sources
Sources:
| Package | Purpose |
|---|---|
Cratis.Chronicle |
Cratis.Chronicle.Compliance.GDPR, Cratis.Chronicle.SubjectAttribute, IEventSequence.Redact, IReadModels.Release |
Cratis.Chronicle.CodeAnalysis |
CHR0026, CHR0034, CHR0035, CHR0043, CHR0046 |
Reverify product sources before claiming support for another version.
Mark personal data with [PII]
Cratis.Chronicle.Compliance.GDPR.PIIAttribute marks a value as personal data.
It targets a class, a property, or a constructor parameter, and it is not
repeatable.
using Cratis.Chronicle.Compliance;
using Cratis.Chronicle.Compliance.GDPR;
[EventType]
public record <PersonEventName>(
[property: PII] string <PersonalPropertyName>,
<NonPersonalType> <BusinessPropertyName>);
On a positional record the attribute must be written as [property: PII] or
placed on the constructor parameter; Chronicle looks for it on the property, the
property's declaring type, the property's own type, and the matching primary
constructor parameter.
Marking the concept type itself makes the value personal everywhere it appears, which is usually what you want for an email, a phone number, or a personal name:
[PII]
[ComplianceDetails("<why this value is collected and under what basis>")]
public record <ConceptName>(string Value) : ConceptAs<string>(Value);
PIIAttribute accepts an optional details string, but Chronicle never reads
it. The rationale that actually reaches the event schema comes from
Cratis.Chronicle.Compliance.ComplianceDetailsAttribute. Write [PII] for the
marker and [ComplianceDetails("...")] for the reason; do not write
[PII("reason")] and expect the reason to be recorded.
PII is the only compliance category Chronicle defines. The protection markers
are [PII] for personal data and [Encrypted] for retained operational secrets;
there is no [Redact], [Erase], [Anonymize], or [Encrypt] annotation.
Redaction is an API call. [NotAudited] belongs to Arc, not Chronicle.
[Encrypted] (Cratis.Chronicle.ProtectedValues) is a
security marker, not a compliance category: it encrypts an operational secret
(API key, token, a company's bank account number) at rest with no data subject
and no erasure. Never put it on a value that is also [PII] (analyzer
CHR0053, which [PII] alone already covers), nor on an event source id
(CHR0052). Arc's [NotAudited] is not a Chronicle attribute either; a secret
that is also a command property takes both [Encrypted] and [NotAudited].
EncryptedAttribute.Scope supports EncryptionScope.Subject (default),
Namespace, and Global; these are security-key scopes, not PII erasure.
PIIManager refuses to delete security keys. Custom security metadata providers
live in Cratis.Chronicle.Confidentiality (ICanProvideSecurityMetadataForType
and ICanProvideSecurityMetadataForProperty).
Requires Chronicle 19.54.1 for encrypted non-string properties/concepts (such as
int and bool) to append and deserialize with their original types across
subject, namespace and global scopes. Check the kernel version; earlier kernels
can fail those appends. Verify a protected-value round trip, not only compilation.
Mark only genuinely personal values. Business metadata, identifiers of non-persons, and amounts stay unmarked — every marked value costs an encryption round trip and becomes unreadable the moment the subject is erased.
Decide the subject
The subject is the natural person a value belongs to, and it is the unit of
erasure. Cratis.Chronicle.SubjectAttribute marks the value that supplies it.
The attribute is a pure marker with no arguments and targets a property or a
constructor parameter.
For an appended event, Chronicle uses the explicit subject when one is supplied
and otherwise falls back to the event source id. That default is the shape you
want: a person-per-stream model needs no [Subject] at all.
[EventType]
public record <PersonEventName>(
[property: Subject] <SubjectValueType> <SubjectPropertyName>,
[property: PII] string <PersonalPropertyName>);
Add [Subject] only when the person is not the event source — for example
an event on an order stream that carries the customer's personal data. A
reactor can supply the subject for its side-effect events by implementing
Cratis.Chronicle.Events.ICanProvideSubject, whose single member is
Subject GetSubject().
Cratis.Chronicle.Subject is record Subject(string Value) : ConceptAs<string>
with a NotSet value, an IsSet test, and implicit conversion from string,
Guid, and EventSourceId.
For a read model instance, Chronicle resolves the subject from the [Subject]
property that has a value, then the [Subject] constructor parameter, then a
property named Id. A stored document carries one default subject; keep one
person's personal data in one document rather than mixing several people into
one row.
Do not put [Subject] or [PII] on the stream identity
An EventSourceId<T>-derived value already is both the key and the compliance
subject.
[Key]or[Subject]on it is redundant — analyzer CHR0026 (warning).[PII]on it is rejected — analyzer CHR0034 (error), and at runtimeCratis.Chronicle.Compliance.GDPR.PIINotSupportedOnEventSourceId.
Chronicle cannot encrypt an event source id. When the natural identifier is
itself sensitive, use a random surrogate stream id and carry the sensitive value
as a [PII] property.
Reserved read-model property names
Chronicle stamps __subject and __subjects onto stored read-model documents.
Analyzer CHR0035 (error) rejects a [ReadModel] that declares _subject,
__subject, or __subjects. Rename the property.
Erase a subject
IEventStore.PII exposes Cratis.Chronicle.Compliance.GDPR.IPIIManager:
Task DeleteEncryptionKeyFor(EncryptionKeyIdentifier identifier);
Task AllowNewEncryptionKeyFor(EncryptionKeyIdentifier identifier);
EncryptionKeyIdentifier is a ConceptAs<string> with implicit conversion from
string, so the subject value can be passed directly:
var eventStore = await chronicleClient.GetEventStore("<EventStoreName>");
await eventStore.PII.DeleteEncryptionKeyFor("<subject-value>");
What this does and does not do:
- It destroys the subject's key and records an erasure fence so a later write cannot resurrect a key for that subject. The fence is monotonic and is recorded before any key is deleted.
- The events stay in the log. Their
[PII]values remain as unreadable ciphertext — this is crypto-shredding, not deletion. - Released values depend on the schema: string → empty string; non-nullable
number/boolean →
0/false; nullable number/boolean →null; collection → empty collection; object/value object → empty object. An erased0,falseor empty string is indistinguishable from a genuinely recorded one. Source:Documentation/compliance/erasing-a-subject.mdx. - Appending a new
[PII]value for an erased subject fails withEncryptionKeyErased. It does not quietly mint a new key. CallAllowNewEncryptionKeyFordeliberately if the subject must be re-enrolled. - A partially completed erasure throws
EncryptionKeyErasureIncomplete, which carries the individual failures. Treat it as unfinished and retry — the fence is already in place, so retrying is safe.
Erasure covers every event store in one namespace, not just the store from
which PII was resolved: forwarding copies subject keys within that namespace.
There is no cross-namespace erasure. A request spanning tenants is one call per
tenant namespace; completing only some is an incomplete erasure.
Redact a stored event
Erasure removes a subject's readability. Redaction removes a specific event's
content. Cratis.Chronicle.EventSequences.IEventSequence exposes both forms:
Task Redact(EventSequenceNumber sequenceNumber, RedactionReason reason);
Task Redact(EventSourceId eventSourceId, RedactionReason reason, params Type[] clrEventTypes);
RedactionReason is a ConceptAs<string> with an Unknown value and implicit
conversion from string. Chronicle records the redaction itself as an
EventRedacted event, so the fact that a redaction happened stays auditable.
Use redaction for content that should never have been appended. Use key erasure for a subject exercising a right to erasure. They are different mechanisms and one does not imply the other.
Requires Chronicle 19.11.0 for redaction to also drop retained causation property values, revision
history and content hashes. It does not reach backups, oplogs or events already
forwarded elsewhere. Subject erasure does not erase causation values: these
are not encrypted under the subject key. Kernel configuration
events.causationPropertyRetention = Omit
(Cratis__Chronicle__Events__CausationPropertyRetention) prevents new retention
on appends, forwarding, revisions and redactions; it does not rewrite history.
Source: Documentation/hosting/configuration/events.md and
Documentation/compliance/erasing-a-subject.mdx.
Adding [PII] / [Encrypted] to an existing generation is accepted with a warning
and protects later events only. Revision and migration fail rather than
persist empty substitutes when key lookup/decryption fails; an erased subject
migrates as erased. Do not confuse that fail-closed write path with read release.
Read personal data back
The kernel decrypts on the paths it owns, so projections and observers see plain
values. When a read-model instance is fetched outside those paths, decrypt it
explicitly through Cratis.Chronicle.ReadModels.IReadModels:
Task<TReadModel> Release<TReadModel>(TReadModel instance);
Task<IEnumerable<TReadModel>> Release<TReadModel>(IEnumerable<TReadModel> instances);
Release degrades quietly by design: it returns the instance unchanged when no
subject can be derived, when the type carries no compliance metadata, or when
decryption fails. It logs, it does not throw. Do not treat a value that came
back looking encrypted as proof the data is intact — check the subject
resolution first.
The asymmetry is deliberate and worth knowing: applying compliance on append fails loudly, releasing it on read fails quietly.
Setup
An ASP.NET Core host that calls builder.AddCratisChronicle() needs no
compliance setup — AddCompliance() is already called for you, and the raw
client path discovers the metadata providers by convention. The developer-facing
requirement is only to annotate the types.
Key storage is per namespace and is a hosting decision, not an application one. Chronicle ships
MongoDB (the default), SQL, in-memory, HashiCorp Vault, and Azure Key Vault key
storage, configured under Cratis:Chronicle:Compliance:Encryption.
From 19.99.1, Azure Key Vault erasure purges every key revision, not just
soft-deletes it. The vault must grant purge permission and have purge protection
disabled; a refused purge fails erasure rather than reporting success. Do not
silently weaken the erasure contract to fit a protected vault. Verified at
v19.110.1, Source/Kernel/Storage.AzureKeyVault/AzureKeyVaultEncryptionKeyStorage.cs
and Documentation/hosting/azure.md.
Operational trap. Switching to a dedicated compliance key store without setting
MigrateFromDefaultStorageleaves every existing key unreachable. Every[PII]value then reads back as an empty string, with no exception and no log — byte-for-byte indistinguishable from a completed erasure. Verify the migration flag before switching stores, and confirm a known subject still reads after the switch.
Restore order. The erasure fence is kept inside the key store, so a key store restored from before an erasure brings the key back without its fence and the erased personal data reads again; a key store older than the storage also lacks keys for newer subjects, and their values read as empty. Restore the certificate ring first, then the storage, then the key store to the storage's point in time.
Modeling rules that follow from erasure
- Prefer one subject per event stream for person-level personal data. The default subject is then correct everywhere and erasure is one call.
- A key redirected away from the event's own stream can carry a
[PII]value across a compliance subject boundary — analyzers CHR0043 and CHR0046 (warnings) flag that shape. Treat the warning as a modeling question, not noise: which person owns the resulting document? - Bearer tokens, magic links, and signed URLs are secrets, not durable facts.
Store a keyed hash or an opaque reference. Chronicle has no attribute that
withholds a secret from the log (Arc's
[NotAudited]keeps a command property out of the causation chain — see cratis-arc-command), and a secret placed in an event payload is in the log for good;[Encrypted]protects it at rest but it stays recoverable, so prefer a hash or reference. - Erasure is wider than the event log. Crypto-shredding removes readability
of
[PII]values in events and read models. It does nothing for a copy that left Chronicle: an exported CSV, a generated PDF, a search index, an email body, a blob the command uploaded, a database backup, or a restored encryption-key backup that makes shredded ciphertext readable again. Model the erasure request as a flow that covers those destinations too — and decide, with the product owner, what happens when a backup is restored (re-erase on restore, or a fence that refuses to restore keys). Those are product and legal decisions; this skill only insists they are made, not left implicit. - If a subject boundary cannot be made person-level without changing product behavior, stop and surface the trade-off before implementing.
Verify
- Every value that identifies or describes a natural person carries
[PII]; business metadata does not. - Rationale is written with
[ComplianceDetails], not with a[PII]argument. - The subject is explicit wherever the person is not the event source, and absent where the event source already is the person.
- No
[Key],[Subject], or[PII]sits on anEventSourceId<T>value. - No read model declares
_subject,__subject, or__subjects. - One stored read-model document holds one person's personal data.
- Erasure is executed per namespace, and an incomplete erasure is retried rather than reported as done.
- Reads that must show personal data outside the kernel's own paths call
Release, and an unchanged instance is investigated rather than assumed. - The build is clean with zero
CHR00xxdiagnostics outstanding, and the relevant specifications pass against the verified package version.