feat: support explicit per-function encryption opt-out (tri-state)

src/cachekit/cache_handler.py

@@ -224,8 +224,9 @@ class CacheSerializationHandler:
     - Encryption: Defines WHETHER to encrypt (security layer on top, orthogonal)
     - Tenant extraction: For multi-tenant encryption key isolation (FAIL CLOSED)
 
-    Modes:
-    - encryption=False: Direct serialization (plaintext in cache)
+    Modes (encryption is tri-state: None=auto / True=force-on / False=hard opt-out):
+    - encryption=None: Auto-detect from CACHEKIT_MASTER_KEY (single-tenant if a key is present)
+    - encryption=False: Explicit opt-out — direct serialization (plaintext), even if a master key is set
     - encryption=True, tenant_extractor=None: Single-tenant encrypted (nil UUID)
     - encryption=True, tenant_extractor provided: Multi-tenant encrypted (FAIL CLOSED)
 
@@ -265,7 +266,7 @@ class CacheSerializationHandler:
     def __init__(
         self,
         serializer_name: Union[str, SerializerProtocol] = "default",  # type: ignore[name-defined]
-        encryption: bool = False,
+        encryption: bool | None = None,
         tenant_extractor: Any | None = None,
         single_tenant_mode: bool = False,
         deployment_uuid: Optional[str] = None,
@@ -278,7 +279,12 @@ def __init__(
             serializer_name: Serializer instance or name. Accepts either:
                             - String name: "default" (MessagePack), "arrow" (DataFrame zero-copy), "orjson" (JSON)
                             - SerializerProtocol instance: Custom serializer implementing the protocol
-            encryption: Enable encryption layer (wraps serializer with EncryptionWrapper)
+            encryption: Tri-state encryption control (wraps serializer with EncryptionWrapper):
+                        - None (default): auto-detect from CACHEKIT_MASTER_KEY. Single-tenant mode
+                          is auto-enabled when a master key is present.
+                        - True: force encryption ON (requires a master key + explicit tenant mode).
+                        - False: explicit hard opt-out. Never encrypts, even when CACHEKIT_MASTER_KEY
+                          is set fleet-wide. This is the deliberate per-function escape hatch.
             tenant_extractor: Optional TenantContextExtractor for multi-tenant encryption.
                              Only used if encryption=True.
                              If None: single-tenant mode (uses nil UUID).
@@ -305,16 +311,24 @@ def __init__(
         self.enable_integrity_checking = enable_integrity_checking
         self._deployment_uuid_value: Optional[str] = None
 
-        # Auto-detect encryption from CACHEKIT_MASTER_KEY when not explicitly configured.
-        # This is the single convergence point for ALL backends and presets.
-        if not encryption and master_key is None and tenant_extractor is None:
-            from cachekit.config.singleton import get_settings
-
-            settings = get_settings()
-            if settings.master_key:
-                encryption = True
-                master_key = settings.master_key.get_secret_value()
-                single_tenant_mode = True
+        # Tri-state encryption resolution. `encryption` is None/True/False:
+        #   None  -> auto-detect from CACHEKIT_MASTER_KEY (fleet-wide convergence point)
+        #   True  -> explicit force-on (validated below)
+        #   False -> explicit hard opt-out; honored even when a master key is present
+        #
+        # Auto-detection is the ONLY path that may flip encryption on and auto-set
+        # single_tenant_mode. An explicit False MUST NOT be promoted to True just
+        # because CACHEKIT_MASTER_KEY exists (issue #128).
+        if encryption is None:
+            encryption = False
+            if master_key is None and tenant_extractor is None:
+                from cachekit.config.singleton import get_settings
+
+                settings = get_settings()
+                if settings.master_key:
+                    encryption = True
+                    master_key = settings.master_key.get_secret_value()
+                    single_tenant_mode = True
 
         self.encryption = encryption
         self.tenant_extractor = tenant_extractor

src/cachekit/config/nested.py

@@ -290,20 +290,35 @@ class EncryptionConfig:
     single_tenant_mode automatically; if using EncryptionConfig directly (e.g. with
     @cache.io), you must set it explicitly.
 
+    Tri-state ``enabled`` (issue #128): a plain bool cannot tell "user left it unset"
+    from "user explicitly disabled", so a deliberate opt-out was silently overridden by
+    fleet-wide CACHEKIT_MASTER_KEY auto-detection. ``enabled`` is therefore None/True/False:
+        - None (default): unset — defer to CACHEKIT_MASTER_KEY auto-detection downstream.
+        - True: force client-side encryption ON (requires master_key + tenant mode).
+        - False: explicit hard opt-out — never encrypt, even when a master key is present.
+
     Attributes:
-        enabled: Enable client-side encryption (default: False)
-        master_key: Hex-encoded master key for key derivation (required if enabled)
+        enabled: Tri-state encryption flag (default: None = unset/auto-detect).
+                 True = force-on, False = explicit opt-out.
+        master_key: Hex-encoded master key for key derivation (required if enabled=True)
         tenant_extractor: Optional callable for per-tenant key derivation (default: None)
         single_tenant_mode: Explicitly enable single-tenant mode (default: False)
         deployment_uuid: Optional deployment-specific UUID for single-tenant mode (default: None)
 
     Examples:
-        Disabled by default (no encryption):
+        Unset by default (defers to auto-detection, no encryption forced):
 
         >>> config = EncryptionConfig()
-        >>> config.enabled
+        >>> config.enabled is None
+        True
+        >>> config.validate()  # No error when unset
+
+        Explicit opt-out (never encrypts, even with CACHEKIT_MASTER_KEY set):
+
+        >>> off = EncryptionConfig(enabled=False)
+        >>> off.enabled
         False
-        >>> config.validate()  # No error when disabled
+        >>> off.validate()  # No error when explicitly disabled
 
         Single-tenant encryption:
 
@@ -326,7 +341,7 @@ class EncryptionConfig:
         cachekit.config.validation.ConfigurationError: Encryption requires explicit tenant mode...
     """
 
-    enabled: bool = False
+    enabled: bool | None = None
     master_key: str | None = field(default=None, repr=False)
     tenant_extractor: Callable[..., str] | None = None
     single_tenant_mode: bool = False
@@ -335,10 +350,18 @@ class EncryptionConfig:
     def validate(self) -> None:
         """Validate encryption configuration.
 
+        Only the explicit force-on state (enabled=True) requires a master key. The
+        unset (None) and explicit opt-out (False) states are both falsy and skip
+        validation — None defers to downstream auto-detection, False never encrypts.
+
+        The master key may be supplied inline or via the CACHEKIT_MASTER_KEY env var
+        (resolved here so force-on works fleet-wide without inlining the key, matching
+        the handler's own resolution).
+
         Raises:
-            ConfigurationError: If encryption enabled but master_key not set
+            ConfigurationError: If encryption enabled but no master_key (inline or env)
         """
-        if self.enabled and not self.master_key:
+        if self.enabled and not self._resolve_master_key():
             raise ConfigurationError(
                 "encryption.enabled=True requires encryption.master_key. "
                 "Set CACHEKIT_MASTER_KEY environment variable or pass master_key parameter."
@@ -357,3 +380,17 @@ def validate(self) -> None:
                     "Cannot use both tenant_extractor and single_tenant_mode. "
                     "Choose multi-tenant (tenant_extractor) OR single-tenant (single_tenant_mode=True)."
                 )
+
+    def _resolve_master_key(self) -> str | None:
+        """Resolve the master key from the inline value, falling back to env settings.
+
+        Inline master_key takes precedence; otherwise read CACHEKIT_MASTER_KEY via the
+        settings singleton. Mirrors validate_encryption_config so the config-level and
+        handler-level views of "is a key available?" stay consistent.
+        """
+        if self.master_key:
+            return self.master_key
+        from cachekit.config.singleton import get_settings
+
+        settings = get_settings()
+        return settings.master_key.get_secret_value() if settings.master_key else None

src/cachekit/config/validation.py

@@ -30,14 +30,15 @@ class ConfigurationError(Exception):
     pass
 
 
-def validate_encryption_config(encryption: bool = False, master_key: str | None = None) -> None:
+def validate_encryption_config(encryption: bool | None = False, master_key: str | None = None) -> None:
     """Validate encryption configuration when encryption is enabled.
 
     Checks for a master key: first from the explicit parameter, then from
     CACHEKIT_MASTER_KEY env var via pydantic-settings.
 
     Args:
-        encryption: Whether encryption is enabled. If False, no validation.
+        encryption: Tri-state encryption flag. Falsy (None unset / False opt-out) skips
+                    validation; only an explicit True requires a resolvable master key.
         master_key: Explicit master key (hex string). Takes precedence over env var.
 
     Raises:

src/cachekit/decorators/intent.py

@@ -144,6 +144,28 @@ def decorator(f: F) -> F:
             existing_l1 = manual_overrides.pop("l1", L1CacheConfig())
             manual_overrides["l1"] = replace(existing_l1, enabled=l1_enabled)
 
+        # Map flattened tri-state encryption flag + related kwargs to nested EncryptionConfig.
+        # Tri-state (issue #128): @cache(encryption=False) is a DELIBERATE opt-out that must
+        # survive fleet-wide CACHEKIT_MASTER_KEY auto-detection. None=auto, True=force, False=off.
+        #
+        # Scope: ONLY the bare/default decorator path (no config=, no _intent). Intent presets
+        # (.secure, .io, ...) own their encryption-param handling, and config= is the RORO form.
+        # An already-constructed EncryptionConfig passes through untouched — wrapping it again
+        # would nest EncryptionConfig inside EncryptionConfig.enabled.
+        if config is None and _intent is None:
+            from cachekit.config.nested import EncryptionConfig
+
+            _enc_passthrough = isinstance(manual_overrides.get("encryption"), EncryptionConfig)
+            _enc_keys = {"encryption", "master_key", "tenant_extractor", "single_tenant_mode", "deployment_uuid"}
+            if not _enc_passthrough and (_enc_keys & manual_overrides.keys()):
+                enc_overrides: dict[str, Any] = {}
+                if "encryption" in manual_overrides:
+                    enc_overrides["enabled"] = manual_overrides.pop("encryption")
+                for _k in ("master_key", "tenant_extractor", "single_tenant_mode", "deployment_uuid"):
+                    if _k in manual_overrides:
+                        enc_overrides[_k] = manual_overrides.pop(_k)
+                manual_overrides["encryption"] = replace(EncryptionConfig(), **enc_overrides)
+
         # RORO config takes highest precedence
         if config is not None:
             # DecoratorConfig instance provided - use it directly with overrides

src/cachekit/decorators/wrapper.py

@@ -281,7 +281,7 @@ def create_cache_wrapper(
     # Serialization & Security
     serializer: Union[str, SerializerProtocol] = "default",  # type: ignore[name-defined]
     integrity_checking: bool = True,
-    encryption: bool = False,
+    encryption: bool | None = None,
     tenant_extractor: TenantContextExtractor | None = None,
     single_tenant_mode: bool = False,
     deployment_uuid: str | None = None,
@@ -318,8 +318,13 @@ def create_cache_wrapper(
         serializer: Serializer instance or name. Accepts either:
                    - String name: "default" (MessagePack), "arrow" (DataFrame zero-copy)
                    - SerializerProtocol instance: Custom serializer implementing the protocol
-        encryption: Enable zero-knowledge encryption layer (AES-256-GCM).
-                   Orthogonal to serializer - wraps ANY serializer with encryption.
+        encryption: Tri-state zero-knowledge encryption control (AES-256-GCM), orthogonal
+                   to serializer - wraps ANY serializer with encryption.
+                   - None (default): auto-detect from CACHEKIT_MASTER_KEY (fleet-wide opt-in).
+                   - True: force encryption ON.
+                   - False: explicit per-function opt-out — never encrypts, even when
+                     CACHEKIT_MASTER_KEY is set. Use to exclude a single function from
+                     fleet-wide encryption (issue #128).
         tenant_extractor: Optional tenant ID extractor for multi-tenant encryption.
                          Only used if encryption=True.
                          If None: single-tenant mode (uses nil UUID for encryption).

tests/unit/config/test_nested_configs.py

@@ -288,9 +288,13 @@ class TestEncryptionConfig:
     """Test EncryptionConfig validation (master_key + tenant mode)."""
 
     def test_defaults(self) -> None:
-        """Test default values."""
+        """Test default values.
+
+        enabled defaults to None (tri-state, issue #128): unset means "defer to
+        CACHEKIT_MASTER_KEY auto-detection", distinct from an explicit False opt-out.
+        """
         config = EncryptionConfig()
-        assert config.enabled is False
+        assert config.enabled is None
         assert config.master_key is None
         assert config.tenant_extractor is None
         assert config.single_tenant_mode is False