Chronicle.Erasure (chronicle v0.1.1)

Copy Markdown

Authenticated encryption for data that may later become unrecoverable.

Chronicle encrypts the normalized value with AES-256-GCM under a keyring-managed data-encryption key. The signed ledger stores the ciphertext, authentication tag, nonce, format, and opaque key identifier—never the plaintext or key. Ledger verification therefore continues to authenticate the exact stored evidence after destroy/1 makes the value unrecoverable.

This control applies only to values marked before they are written. It cannot remove plaintext already committed to an older entry. Destroying a key is irreversible and is appropriate only after the application has applied its retention and legal-hold policy.

Summary

Types

envelope()

Functions

decrypt(envelope)

Decrypts one Chronicle erasable envelope while its key remains available.

destroy(key_id)

Irreversibly destroys the key named by key_id through the configured erasure keyring.

encrypt(value, key_id)

Encrypts a value under the destroyable key named by key_id.

Types

envelope()

@type envelope() :: %{required(String.t()) => String.t()}

Functions

decrypt(envelope)

@spec decrypt(envelope()) :: {:ok, term()} | {:error, term()}

Decrypts one Chronicle erasable envelope while its key remains available.

After successful key destruction this returns {:error, {:erasure_key_unavailable, key_id}}. Authentication failure is reported separately; no unauthenticated plaintext is returned.

destroy(key_id)

@spec destroy(String.t()) :: :ok | {:error, term()}

Irreversibly destroys the key named by key_id through the configured erasure keyring.

The keyring must not report success while a provider recovery window or replica can still resolve the key.

encrypt(value, key_id)

@spec encrypt(term(), String.t()) :: {:ok, envelope()} | {:error, term()}

Encrypts a value under the destroyable key named by key_id.

Application code normally uses Chronicle.erasable/2, which defers this operation until Chronicle normalizes the surrounding event or snapshot.