Add encryption and compression to storage backend

Implement transparent AES-256-GCM encryption and zlib compression for
document storage via a new TransformAdapter. This provides at-rest
encryption without modifying existing adapters.

Features:
- AES-256-GCM encryption (hardware-accelerated on modern CPUs)
- zlib compression to reduce storage size
- Backwards-compatible: reads legacy unencrypted documents
- Supports both disk and S3 storage backends
- Configurable via MARKDOC_ENCRYPTION_KEY and MARKDOC_COMPRESSION_ENABLED

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: ajha-dev

config/config.exs

@@ -58,7 +58,12 @@ config :markdoc, :storage,
   idle_flush_ms: 300_000,
   retention_hours: 24,
   cleanup_interval_ms: 900_000,
-  s3_prefix: "documents/"
+  s3_prefix: "documents/",
+  # Encryption: Base64-encoded 32-byte key (nil to disable)
+  # Generate with: openssl rand -base64 32
+  encryption_key: nil,
+  # Compression: Enable zlib compression (works with or without encryption)
+  compression_enabled: true
 
 # Import environment specific config. This must remain at the bottom
 # of this file so it overrides the configuration defined above.

config/runtime.exs

@@ -105,6 +105,36 @@ env_backend =
     _ -> Keyword.get(base_storage_config, :backend, :none)
   end
 
+# Encryption key: Base64-encoded 32-byte key
+# Generate with: openssl rand -base64 32
+env_encryption_key =
+  case System.get_env("MARKDOC_ENCRYPTION_KEY") do
+    nil ->
+      Keyword.get(base_storage_config, :encryption_key)
+
+    base64_key ->
+      case Markdoc.Storage.TransformAdapter.decode_key(base64_key) do
+        {:ok, key} ->
+          key
+
+        {:error, reason} ->
+          raise """
+          Invalid MARKDOC_ENCRYPTION_KEY: #{inspect(reason)}
+          The key must be a Base64-encoded 32-byte (256-bit) value.
+          Generate one with: openssl rand -base64 32
+          """
+      end
+  end
+
+# Compression: enabled by default
+env_compression_enabled =
+  case System.get_env("MARKDOC_COMPRESSION_ENABLED") do
+    "false" -> false
+    "true" -> true
+    nil -> Keyword.get(base_storage_config, :compression_enabled, true)
+    _ -> Keyword.get(base_storage_config, :compression_enabled, true)
+  end
+
 config :markdoc, :storage,
   backend: env_backend,
   disk_path: System.get_env("MARKDOC_STORAGE_PATH") || Keyword.get(base_storage_config, :disk_path),
@@ -117,7 +147,9 @@ config :markdoc, :storage,
   retention_hours:
     env_int.("MARKDOC_RETENTION_HOURS", Keyword.get(base_storage_config, :retention_hours, 24)),
   cleanup_interval_ms:
-    env_int.("MARKDOC_CLEANUP_INTERVAL_MS", Keyword.get(base_storage_config, :cleanup_interval_ms, 900_000))
+    env_int.("MARKDOC_CLEANUP_INTERVAL_MS", Keyword.get(base_storage_config, :cleanup_interval_ms, 900_000)),
+  encryption_key: env_encryption_key,
+  compression_enabled: env_compression_enabled
 
 # ExAws (S3) runtime configuration for AWS or S3-compatible endpoints
 exaws_region = System.get_env("MARKDOC_S3_REGION") || System.get_env("AWS_REGION") || System.get_env("AWS_DEFAULT_REGION")

lib/markdoc/storage.ex

@@ -4,9 +4,22 @@ defmodule Markdoc.Storage do
 
   Selects the configured adapter and exposes helper functions for load, persist,
   delete, and retention settings.
+
+  ## Encryption
+
+  When `encryption_key` is configured, documents are stored with AES-256-GCM
+  encryption and zlib compression. The encryption key should be a Base64-encoded
+  32-byte (256-bit) key.
+
+  Generate a key with: `openssl rand -base64 32`
+
+  ## Configuration
+
+  - `:encryption_key` - Base64-encoded 32-byte key (nil to disable encryption)
+  - `:compression_enabled` - Enable zlib compression (default: true)
   """
 
-  alias Markdoc.Storage.{DiskAdapter, S3Adapter, NoopAdapter}
+  alias Markdoc.Storage.{DiskAdapter, S3Adapter, NoopAdapter, TransformAdapter}
 
   @type doc_id :: Markdoc.Storage.Adapter.doc_id()
   @type doc_payload :: Markdoc.Storage.Adapter.doc_payload()
@@ -59,30 +72,69 @@ defmodule Markdoc.Storage do
     Path.expand(path)
   end
 
+  def encryption_key do
+    case Keyword.get(config(), :encryption_key) do
+      nil -> nil
+      key when is_binary(key) -> key
+    end
+  end
+
+  def compression_enabled? do
+    Keyword.get(config(), :compression_enabled, true)
+  end
+
   defp config, do: Application.get_env(:markdoc, :storage, [])
 
   defp adapter_with_opts do
     cfg = config()
+    backend = Keyword.get(cfg, :backend, :none)
+    encryption_key = Keyword.get(cfg, :encryption_key)
+    compression_enabled = Keyword.get(cfg, :compression_enabled, true)
 
-    case Keyword.get(cfg, :backend, :none) do
+    case backend do
       :none ->
         {:ok, {NoopAdapter, []}}
 
       :disk ->
-        {:ok, {DiskAdapter, [path: disk_path()]}}
+        if encryption_key do
+          # Use TransformAdapter with disk storage
+          opts = [
+            storage_type: :disk,
+            path: disk_path(),
+            encryption_key: encryption_key,
+            compression_enabled: compression_enabled
+          ]
+
+          {:ok, {TransformAdapter, opts}}
+        else
+          {:ok, {DiskAdapter, [path: disk_path()]}}
+        end
 
       :s3 ->
         bucket = Keyword.get(cfg, :s3_bucket)
 
         if is_nil(bucket) do
           {:error, :missing_bucket}
         else
-          {:ok,
-           {S3Adapter,
-            [
+          if encryption_key do
+            # Use TransformAdapter with S3 storage
+            opts = [
+              storage_type: :s3,
               bucket: bucket,
-              prefix: Keyword.get(cfg, :s3_prefix, "documents/")
-            ]}}
+              prefix: Keyword.get(cfg, :s3_prefix, "documents/"),
+              encryption_key: encryption_key,
+              compression_enabled: compression_enabled
+            ]
+
+            {:ok, {TransformAdapter, opts}}
+          else
+            {:ok,
+             {S3Adapter,
+              [
+                bucket: bucket,
+                prefix: Keyword.get(cfg, :s3_prefix, "documents/")
+              ]}}
+          end
         end
     end
   end