feat: 2-arg Access errors on header_enabled=true configurations

Per design decision 2026-05-17, the two-argument Access(value, name) is
for header_enabled=false configurations only — it treats the input as
raw headerless ciphertext. For headered configurations, the header
itself identifies the configuration, so Access(value) is the right call.

Previously Access(value, name) silently stripped the header on the
explicit path, which made the API ambiguous (callers couldn't tell
whether the value they passed had a header or not). Now it throws
ArgumentException so callers can fix the call site instead of seeing
garbage decrypts.

Implementation: Access(value, name) now checks HeaderEnabled and
throws before dispatching. AccessByHeader strips the header itself
and passes raw ciphertext to AccessFpe, which no longer takes an
explicitConfiguration flag and always assumes its input is headerless.
The strip therefore happens exactly once and only on the header path.

Added TwoArgAccessOnHeaderedConfigRaises; README clarifies that the
two-arg form is only valid for header_enabled=false configurations.

36 tests pass.

Author: lgutschow

README.md

@@ -41,6 +41,12 @@ var encrypted = c.Protect("123-45-6789", "ssn");
 // Access (header-based, no configuration name needed)
 var decrypted = c.Access(encrypted);
 // → "123-45-6789"
+
+// For configurations with header_enabled=false, name the configuration explicitly:
+// var decrypted = c.Access(encrypted, "ssn_unheadered");
+// The two-arg form is only valid for header_enabled=false configurations —
+// calling it on a headered configuration throws ArgumentException because the
+// header itself identifies which configuration to use.
 ```
 
 ## Engines

src/Cyphera/Cyphera.cs

@@ -76,7 +76,10 @@ public string Access(string protectedValue, string? configurationName = null)
             if (configurationName != null)
             {
                 var configuration = GetConfiguration(configurationName);
-                return AccessFpe(protectedValue, configuration, explicitConfiguration: true);
+                if (configuration.HeaderEnabled)
+                    throw new ArgumentException(
+                        $"configuration '{configurationName}' has header_enabled=true; use Access(value) — the header identifies the configuration. The two-arg form is for header_enabled=false configurations only.");
+                return AccessFpe(protectedValue, configuration);
             }
 
             return AccessByHeader(protectedValue);
@@ -90,7 +93,9 @@ public string AccessByHeader(string protectedValue)
                 if (protectedValue.Length > header.Length && protectedValue.StartsWith(header))
                 {
                     var configuration = GetConfiguration(_headerIndex[header]);
-                    return AccessFpe(protectedValue, configuration);
+                    // Strip the header here so AccessFpe always receives raw headerless ciphertext.
+                    var stripped = protectedValue[header.Length..];
+                    return AccessFpe(stripped, configuration);
                 }
             }
 
@@ -127,19 +132,18 @@ private string ProtectFpe(string value, Configuration configuration, bool isFF3)
             return result;
         }
 
-        private string AccessFpe(string protectedValue, Configuration configuration, bool explicitConfiguration = false)
+        // Always assumes `protectedValue` is raw headerless ciphertext. Callers on the
+        // header path strip the header before calling; the explicit-name path is only
+        // valid for header_enabled=false configurations, so no header is present.
+        private string AccessFpe(string protectedValue, Configuration configuration)
         {
             if (configuration.Engine != "ff1" && configuration.Engine != "ff3")
                 throw new ArgumentException($"Cannot reverse '{configuration.Engine}' — not reversible");
 
             var key = ResolveKey(configuration.KeyRef);
             var alphabet = configuration.Alphabet;
 
-            var withoutHeader = protectedValue;
-            if (!explicitConfiguration && configuration.HeaderEnabled && configuration.Header != null)
-                withoutHeader = protectedValue[configuration.Header.Length..];
-
-            var (encryptable, positions, chars) = ExtractPassthroughs(withoutHeader, alphabet);
+            var (encryptable, positions, chars) = ExtractPassthroughs(protectedValue, alphabet);
 
             string decrypted;
             if (configuration.Engine == "ff3")

tests/Cyphera.Tests/CypheraClientTests.cs

@@ -134,5 +134,20 @@ public void CrossLanguageVector()
             var result = c.Protect("123-45-6789", "ssn");
             Assert.Equal("T01i6J-xF-07pX", result);
         }
+
+        // ── New error condition: 2-arg Access on headered config ──
+
+        [Fact]
+        public void TwoArgAccessOnHeaderedConfigRaises()
+        {
+            var c = CreateClient();
+            var protected_ = c.Protect("123-45-6789", "ssn");
+            // ssn has header_enabled=true; Access(value, "ssn") must error rather
+            // than silently return garbage. Callers should use Access(value) so
+            // the header identifies the configuration.
+            var ex = Assert.Throws<ArgumentException>(() => c.Access(protected_, "ssn"));
+            Assert.Contains("header_enabled=true", ex.Message);
+            Assert.Contains("ssn", ex.Message);
+        }
     }
 }