Encrypt operational secrets in Cratis Chronicle
Use [Encrypted] in Cratis Chronicle to encrypt a non-personal operational secret at rest without including it in personal-data erasure. A partner credential or webhook signing secret can need this protection even though it is not data about a person.
If the value is personally identifiable information (PII), use [PII] instead. That marker encrypts personal data and includes it in Chronicle’s erasure mechanism for the General Data Protection Regulation (GDPR). The Security overview explains how choosing the wrong marker can make a non-personal secret unreadable when a person’s key is erased.
The marker
Section titled “The marker”[AttributeUsage(AttributeTargets.Class | AttributeTargets.Property | AttributeTargets.Parameter)]public sealed class EncryptedAttribute(EncryptionScope scope = EncryptionScope.Subject, string details = "") : Attribute{ public EncryptionScope Scope { get; } = scope; public string Details { get; } = details;}import io.cratis.chronicle.confidentiality.Encryptedimport io.cratis.chronicle.confidentiality.EncryptionScopeimport io.cratis.chronicle.events.EventType
// annotation class Encrypted(// val scope: EncryptionScope = EncryptionScope.Subject,// val description: String = ""// )// Apply it to a class (a concept type), a property, a field, or a constructor parameter.// Both arguments are optional; description records why the value needs encryption.@EventTypedata class EncryptedMarkerPartnerIntegrationConfigured( @Encrypted(EncryptionScope.Subject, "Partner API credential - an operational secret with no data subject") val apiKey: String)import io.cratis.chronicle.confidentiality.Encrypted;import io.cratis.chronicle.confidentiality.EncryptionScope;import io.cratis.chronicle.events.EventType;
// @interface Encrypted {// EncryptionScope scope() default EncryptionScope.Subject;// String description() default "";// }// Apply it to a class (a concept type), a record component, a field, or a constructor parameter.// Both elements are optional; description records why the value needs encryption.@EventTyperecord EncryptedMarkerPartnerIntegrationConfigured( @Encrypted( scope = EncryptionScope.Subject, description = "Partner API credential - an operational secret with no data subject") String apiKey) {}# Chronicle.Confidentiality.encrypted/1,2,3 - imported automatically inside# modules that `use Chronicle.Events.EventType` or# `use Chronicle.ReadModels.ReadModel`. Marks one struct field.## defmacro encrypted(field, scope \\ :subject, details \\ "")## Chronicle.Concept.encrypted/0,1,2 - imported automatically inside modules# that `use Chronicle.Concept`. Marks the concept's value itself.## defmacro encrypted(scope \\ :subject, details \\ "")import { encrypted, EncryptionScope, eventType } from '@cratis/chronicle';
// encrypted(scope: EncryptionScope = EncryptionScope.Subject, details?: string): PropertyDecorator & ClassDecorator// Apply it to a class (a concept type) or to a property. Both arguments are optional.@eventType()class EncryptedMarkerPartnerIntegrationConfigured { @encrypted(EncryptionScope.Subject, 'Partner API credential - an operational secret with no data subject') apiKey = '';}In .NET, import EncryptedAttribute from Cratis.Chronicle.ProtectedValues. The optional details parameter records why the value needs encryption; it does not change the encryption behavior.
using Cratis.Chronicle.ProtectedValues;import io.cratis.chronicle.confidentiality.Encryptedimport io.cratis.chronicle.confidentiality.Encrypted;# encrypted/1,2,3 is imported automatically inside modules that# `use Chronicle.Events.EventType` or `use Chronicle.ReadModels.ReadModel` -# there is nothing to import explicitly.import { encrypted } from '@cratis/chronicle';Applying to a concept
Section titled “Applying to a concept”When a secret has a dedicated concept type, a type that names that domain value, mark the type itself. Each event property using that type is then encrypted, so you do not have to repeat the marker on every event.
[Encrypted]public record PartnerApiKey(string Value) : ConceptAs<string>(Value);
public record PartnerIntegrationConfiguredWithKey(PartnerApiKey ApiKey);import io.cratis.fundamentals.concepts.ConceptAsimport io.cratis.chronicle.confidentiality.Encrypted
@Encrypteddata class EncryptedAttrPartnerApiKey(val value: String) : ConceptAs<String> { override fun value(): String = value}
data class EncryptedAttrPartnerIntegrationConfiguredWithKey(val apiKey: EncryptedAttrPartnerApiKey)import io.cratis.fundamentals.concepts.ConceptAs;import io.cratis.chronicle.confidentiality.Encrypted;
@Encryptedrecord EncryptedAttrPartnerApiKey(String value) implements ConceptAs<String> {}
record EncryptedAttrPartnerIntegrationConfiguredWithKey(EncryptedAttrPartnerApiKey apiKey) {}defmodule MyApp.Confidentiality.Encrypted.PartnerApiKey do use Chronicle.Concept, type: :string encrypted()end
defmodule MyApp.Events.EncryptedAttrPartnerIntegrationConfiguredWithKey do use Chronicle.Events.EventType, id: "encrypted-attr-partner-integration-configured-with-key"
defstruct api_key: %MyApp.Confidentiality.Encrypted.PartnerApiKey{}endimport { encrypted } from '@cratis/chronicle';import { ConceptAs } from '@cratis/fundamentals';
@encrypted()class EncryptedAttrPartnerApiKey extends ConceptAs<string> { static readonly valueType = String;
constructor(value: string) { super(value); }}
class EncryptedAttrPartnerIntegrationConfiguredWithKey { apiKey: EncryptedAttrPartnerApiKey = new EncryptedAttrPartnerApiKey('');}Applying to an event property
Section titled “Applying to an event property”Mark a single property directly when the value has no dedicated concept type. In this example, Chronicle encrypts ApiKey and leaves PartnerName as plaintext:
public record PartnerIntegrationConfigured( [Encrypted] string ApiKey, string PartnerName);
// When this event is written, ApiKey is encrypted. PartnerName is stored as plaintext.import io.cratis.chronicle.confidentiality.Encryptedimport io.cratis.chronicle.events.EventType
@EventTypedata class EncryptedAttrPartnerIntegrationConfigured( @Encrypted val apiKey: String, val partnerName: String)
// When this event is written, apiKey is encrypted. partnerName is stored as plaintext.import io.cratis.chronicle.confidentiality.Encrypted;import io.cratis.chronicle.events.EventType;
@EventTyperecord EncryptedAttrPartnerIntegrationConfigured( @Encrypted String apiKey, String partnerName) {}
// When this event is written, apiKey is encrypted. partnerName is stored as plaintext.defmodule MyApp.Events.EncryptedAttrPartnerIntegrationConfigured do use Chronicle.Events.EventType, id: "encrypted-attr-partner-integration-configured"
defstruct [:partner_name, :api_key]
encrypted(:api_key, :subject, "Partner API key")end
# When this event is written, api_key is encrypted. partner_name is stored as plaintext.import { encrypted, eventType } from '@cratis/chronicle';
@eventType()class EncryptedAttrPartnerIntegrationConfigured { @encrypted() apiKey = ''; partnerName = '';}
// When this event is written, apiKey is encrypted. partnerName is stored as plaintext.[PII] and [Encrypted] never mix
Section titled “[PII] and [Encrypted] never mix”Choose one marker for each value. [PII] and [Encrypted] select different keys and erasure behavior; combining them is invalid, not extra protection. Schema generation rejects a property that resolves both markers. In .NET, it throws PIIAndEncryptedCombinedNotSupported:
// Throws PIIAndEncryptedCombinedNotSupported at schema-generation time,// and is flagged at compile time by CHR0053.public record EncryptedCustomerRegistered( [PII] [Encrypted] string SomeValue);import io.cratis.chronicle.compliance.Piiimport io.cratis.chronicle.confidentiality.Encryptedimport io.cratis.chronicle.events.EventType
// Throws PiiAndEncryptedCombinedNotSupported at schema-generation time.@EventTypedata class EncryptedAttrCustomerRegistered(@Pii @Encrypted val someValue: String)import io.cratis.chronicle.compliance.Pii;import io.cratis.chronicle.confidentiality.Encrypted;import io.cratis.chronicle.events.EventType;
// Throws PiiAndEncryptedCombinedNotSupported at schema-generation time.@EventTyperecord EncryptedAttrCustomerRegistered(@Pii @Encrypted String someValue) {}# Raises Chronicle.Confidentiality.PiiAndEncryptedCombinedNotSupported at# schema-generation time.## defmodule MyApp.Events.EncryptedAttrCustomerRegistered do# use Chronicle.Events.EventType, id: "encrypted-attr-customer-registered"# defstruct [:some_value]## pii(:some_value)# encrypted(:some_value)# endimport { pii } from '@cratis/chronicle';import { encrypted, eventType } from '@cratis/chronicle';
// Throws PIIAndEncryptedCombinedNotSupported at schema-generation time.@eventType()class EncryptedAttrCustomerRegistered { @pii() @encrypted() someValue = '';}Use [PII] for personal data and [Encrypted] for non-personal operational secrets. In .NET, CHR0053 catches directly visible combinations at compile time. Schema generation also catches combinations inherited through a marked concept type.
Why the two keys are never the same
Section titled “Why the two keys are never the same”A record can contain both a personal email address marked [PII] and a non-personal partner credential marked [Encrypted]. A subject identity tells Chronicle who a protected value belongs to. Even when both values resolve to the same subject, Chronicle stores their keys under different identifiers. Erasing the person’s PII leaves the credential’s key untouched, so the credential can still be decrypted.
The kernel keeps these operations separate:
[Encrypted]key identifiers use a reserved prefix that the PII path does not produce.- The compliance entry points
DeleteEncryptionKeyForandAllowNewEncryptionKeyForrefuse identifiers with that prefix.
The confidentiality API exposes no equivalent erasure operation. Use [PII] for personal data that needs to participate in erasure; [Encrypted] does not provide that behavior.
EncryptionScope determines which values share an encryption key. It does not change the encryption algorithm:
public enum EncryptionScope{ Subject, // per compliance identity - the default Namespace, // one key shared by every value marked this way in the event store namespace Global // one key shared by every value marked this way across the whole installation}import io.cratis.chronicle.confidentiality.EncryptionScope
// EncryptionScope has exactly these three members - the when below is exhaustive over them.fun encryptionScopeKeyBoundary(scope: EncryptionScope): String = when (scope) { EncryptionScope.Subject -> "per compliance identity - the default" EncryptionScope.Namespace -> "one key shared by every value marked this way in the event store namespace" EncryptionScope.Global -> "one key shared by every value marked this way across the whole installation"}import io.cratis.chronicle.confidentiality.EncryptionScope;
// EncryptionScope has exactly these three members - the switch below is exhaustive over them.class EncryptionScopeKeyBoundaries { static String describe(EncryptionScope scope) { return switch (scope) { case Subject -> "per compliance identity - the default"; case Namespace -> "one key shared by every value marked this way in the event store namespace"; case Global -> "one key shared by every value marked this way across the whole installation"; }; }}# The scope is an atom passed as the scope argument of encrypted/...:## :subject - per compliance identity - the default# :namespace - one key shared by every value marked this way in the event store namespace# :global - one key shared by every value marked this way across the whole installationimport { EncryptionScope } from '@cratis/chronicle';
// EncryptionScope is exported by @cratis/chronicle and has exactly these three members.const encryptionScopeKeyBoundaries: Record<EncryptionScope, string> = { [EncryptionScope.Subject]: 'per compliance identity - the default', [EncryptionScope.Namespace]: 'one key shared by every value marked this way in the event store namespace', [EncryptionScope.Global]: 'one key shared by every value marked this way across the whole installation'};Choose the scope that matches the secret’s ownership:
| Scope | Values that share a key |
|---|---|
EncryptionScope.Subject (default) |
Values with the same compliance identity in the event store namespace. This is the subject, or the event source id when none is set, but the key remains separate from any [PII] key for that identity. |
EncryptionScope.Namespace |
Every value marked with this scope in a given event store namespace, regardless of the document’s subject. |
EncryptionScope.Global |
Every value marked with this scope across the whole Chronicle installation, including every event store and namespace. |
For example, use Namespace for a webhook signing secret shared across the partner integrations in that namespace. Global shares a key more broadly, across event stores as well as namespaces. Neither scope is available for [PII]: personal-data erasure remains tied to the compliance identity. See Compliance for that workflow.
[Encrypted]public record PartnerApiKeyScoped(string Value) : ConceptAs<string>(Value); // one key per partner (EncryptionScope.Subject, the default)
[Encrypted(EncryptionScope.Namespace)]public record PartnerWebhookSecret(string Value) : ConceptAs<string>(Value); // one key for every partner in the namespace
[Encrypted(EncryptionScope.Global)]public record LicenseToken(string Value) : ConceptAs<string>(Value); // one key for the whole installationimport io.cratis.fundamentals.concepts.ConceptAsimport io.cratis.chronicle.confidentiality.Encryptedimport io.cratis.chronicle.confidentiality.EncryptionScope
// One key per partner (EncryptionScope.Subject, the default).@Encrypteddata class EncryptedAttrPartnerApiKeyScoped(val value: String) : ConceptAs<String> { override fun value(): String = value}
// One key for every partner in the namespace.@Encrypted(scope = EncryptionScope.Namespace)data class EncryptedAttrPartnerWebhookSecret(val value: String) : ConceptAs<String> { override fun value(): String = value}
// One key for the whole installation.@Encrypted(scope = EncryptionScope.Global)data class EncryptedAttrLicenseToken(val value: String) : ConceptAs<String> { override fun value(): String = value}import io.cratis.fundamentals.concepts.ConceptAs;import io.cratis.chronicle.confidentiality.Encrypted;import io.cratis.chronicle.confidentiality.EncryptionScope;
// One key per partner (EncryptionScope.Subject, the default).@Encryptedrecord EncryptedAttrPartnerApiKeyScoped(String value) implements ConceptAs<String> {}
// One key for every partner in the namespace.@Encrypted(scope = EncryptionScope.Namespace)record EncryptedAttrPartnerWebhookSecret(String value) implements ConceptAs<String> {}
// One key for the whole installation.@Encrypted(scope = EncryptionScope.Global)record EncryptedAttrLicenseToken(String value) implements ConceptAs<String> {}# One key per partner (:subject, the default).defmodule MyApp.Confidentiality.Encrypted.PartnerApiKeyScoped do use Chronicle.Concept, type: :string encrypted()end
# One key for every partner in the namespace.defmodule MyApp.Confidentiality.Encrypted.PartnerWebhookSecret do use Chronicle.Concept, type: :string encrypted(:namespace)end
# One key for the whole installation.defmodule MyApp.Confidentiality.Encrypted.LicenseToken do use Chronicle.Concept, type: :string encrypted(:global)endimport { encrypted, EncryptionScope } from '@cratis/chronicle';import { ConceptAs } from '@cratis/fundamentals';
// One key per partner (EncryptionScope.Subject, the default).@encrypted()class EncryptedAttrPartnerApiKeyScoped extends ConceptAs<string> { static readonly valueType = String;
constructor(value: string) { super(value); }}
// One key for every partner in the namespace.@encrypted(EncryptionScope.Namespace)class EncryptedAttrPartnerWebhookSecret extends ConceptAs<string> { static readonly valueType = String;
constructor(value: string) { super(value); }}
// One key for the whole installation.@encrypted(EncryptionScope.Global)class EncryptedAttrLicenseToken extends ConceptAs<string> { static readonly valueType = String;
constructor(value: string) { super(value); }}Constraints
Section titled “Constraints”EventSourceId is not supported
Section titled “EventSourceId is not supported”Keep the event source identifier in plaintext: Chronicle needs it to correlate events and locate subject-scoped keys when no subject is set. In .NET, schema generation throws EncryptedNotSupportedOnEventSourceId for identifier types derived from EventSourceId / EventSourceId<T> that themselves carry [Encrypted].
Applying [Encrypted] directly to an event source identifier property or record parameter is also prohibited. CHR0052 catches directly marked members whose types derive from EventSourceId<T> at compile time. The example below triggers that diagnostic, not EncryptedNotSupportedOnEventSourceId during schema generation. Do not rely on schema generation to reject directly marked members:
public record PartnerId(Guid Value) : EventSourceId<Guid>(Value);
// CHR0052: [Encrypted] cannot be applied to an EventSourceId<T> member.public record PartnerIntegrationConfiguredWithId( [Encrypted] PartnerId PartnerId, string ApiKey);import io.cratis.chronicle.concepts.EventSourceIdimport io.cratis.chronicle.confidentiality.Encrypted
// This will throw EncryptedNotSupportedOnEventSourceId@Encrypteddata class EncryptedAttrPartnerId(val value: String) : EventSourceId { override fun value(): String = value}import io.cratis.chronicle.concepts.EventSourceId;import io.cratis.chronicle.confidentiality.Encrypted;
// This will throw EncryptedNotSupportedOnEventSourceId@Encryptedrecord EncryptedAttrPartnerId(String value) implements EventSourceId {}# Raises ArgumentError at compile time — encryption is not supported on a# Chronicle.Concept declared with event_source_id: true.## defmodule MyApp.Confidentiality.Encrypted.PartnerId do# use Chronicle.Concept, type: :uuid, event_source_id: true# encrypted()# endimport { encrypted } from '@cratis/chronicle';
// TypeScript has no dedicated EventSourceId<T> type - the event source identifier is always// the conventional 'eventSourceId' property. Marking it @encrypted() throws// EncryptedNotSupportedOnEventSourceId at decoration time, for the same reason C# forbids// [Encrypted] on EventSourceId<T>: encrypting it would make its own decryption key unfindable.class EncryptedAttrPartnerIntegrationConfiguredWithId { @encrypted() eventSourceId = '';}If the identifier itself is a secret, use a non-sensitive surrogate as the event source id and store the secret in a separate [Encrypted] property.
Client coverage
Section titled “Client coverage”Use [Encrypted] in .NET, @encrypted() in TypeScript, @Encrypted in Kotlin/Java, or the encrypted macro in Elixir. The examples above show each client’s syntax. These clients emit security metadata for the kernel to apply encryption and reject a value that resolves both PII and encryption metadata during schema generation.
For read model decryption, continue to Releasing PII and encrypted values. It explains which reads decrypt values automatically and how to release an instance outside that path.