feat: align error messages + strict FF3 tweak (cross-SDK consistency)

lgutschow · lgutschow · commit 2244d8b3ff34 · 2026-05-23T00:36:00.000-04:00
Adopt the canonical spec error-message text so the .NET SDK matches
the rust reference byte-for-byte. Exception types remain
ArgumentException; only the message text inside changes. FF3 tweak
enforcement was already strict (8 bytes) and FF3-1 was already strict
(7 bytes); messages are normalized to the spec-mandated 'invalid
tweak length: N (expected M)' form. ToDigits in FF1/FF3 now reports
the offending char + position instead of throwing KeyNotFoundException.
diff --git a/src/Cyphera/Cyphera.cs b/src/Cyphera/Cyphera.cs
@@ -66,7 +66,7 @@ public string Protect(string value, string configurationName)
                 "ff1" or "ff3" or "ff31" => ProtectFpe(value, configuration),
                 "mask" => ProtectMask(value, configuration),
                 "hash" => ProtectHash(value, configuration),
-                _ => throw new ArgumentException($"Unknown engine: {configuration.Engine}")
+                _ => throw new ArgumentException($"unknown engine: {configuration.Engine}")
             };
         }
 
@@ -80,14 +80,15 @@ public string Access(string protectedValue)
             {
                 if (protectedValue.Length > header.Length && protectedValue.StartsWith(header))
                 {
-                    var configuration = GetConfiguration(_headerIndex[header]);
+                    var name = _headerIndex[header];
+                    var configuration = GetConfiguration(name);
                     // Strip the header here so AccessFpe always receives raw headerless ciphertext.
                     var stripped = protectedValue[header.Length..];
-                    return AccessFpe(stripped, configuration);
+                    return AccessWithConfiguration(stripped, configuration, name);
                 }
             }
 
-            throw new ArgumentException("No matching header found");
+            throw new ArgumentException("no matching header found");
         }
 
         // Escape-hatch access for unique situations where the protected value
@@ -102,6 +103,14 @@ public string Access(string protectedValue, string configurationName)
             if (configurationName == null)
                 throw new ArgumentException("Access(value, configurationName) requires a configuration name.");
             var configuration = GetConfiguration(configurationName);
+            return AccessWithConfiguration(protectedValue, configuration, configurationName);
+        }
+
+        private string AccessWithConfiguration(string protectedValue, Configuration configuration, string configurationName)
+        {
+            if (configuration.Engine == "mask" || configuration.Engine == "hash")
+                throw new ArgumentException(
+                    $"cannot reverse '{configurationName}' — {configuration.Engine} is irreversible");
             return AccessFpe(protectedValue, configuration);
         }
 
@@ -131,7 +140,7 @@ private string ProtectFpe(string value, Configuration configuration)
 
             var (encryptable, positions, chars) = ExtractPassthroughs(value, alphabet);
             if (encryptable.Length == 0)
-                throw new ArgumentException("No encryptable characters in input");
+                throw new ArgumentException("no encryptable characters in input");
 
             string encrypted;
             if (configuration.Engine == "ff3")
@@ -164,8 +173,10 @@ private string ProtectFpe(string value, Configuration configuration)
         // a headerless value.
         private string AccessFpe(string protectedValue, Configuration configuration)
         {
+            // Callers (AccessWithConfiguration) have already filtered mask/hash;
+            // anything else here that isn't an FPE engine is an internal misuse.
             if (configuration.Engine != "ff1" && configuration.Engine != "ff3" && configuration.Engine != "ff31")
-                throw new ArgumentException($"Cannot reverse '{configuration.Engine}' — not reversible");
+                throw new ArgumentException($"unknown engine: {configuration.Engine}");
 
             var key = ResolveKey(configuration.KeyRef);
             var alphabet = configuration.Alphabet;
@@ -198,7 +209,7 @@ private string AccessFpe(string protectedValue, Configuration configuration)
         private static string ProtectMask(string value, Configuration configuration)
         {
             if (string.IsNullOrEmpty(configuration.Pattern))
-                throw new ArgumentException("Mask configuration requires 'pattern'");
+                throw new ArgumentException("mask pattern required");
 
             int len = value.Length;
             return configuration.Pattern switch
@@ -248,16 +259,16 @@ private string ProtectHash(string value, Configuration configuration)
         private Configuration GetConfiguration(string name)
         {
             if (!_configurations.TryGetValue(name, out var configuration))
-                throw new ArgumentException($"Unknown configuration: {name}");
+                throw new ArgumentException($"configuration not found: {name}");
             return configuration;
         }
 
         private byte[] ResolveKey(string? keyRef)
         {
             if (string.IsNullOrEmpty(keyRef))
-                throw new ArgumentException("No key_ref in configuration");
+                throw new ArgumentException("key error: no key_ref in configuration");
             if (!_keys.TryGetValue(keyRef, out var key))
-                throw new ArgumentException($"Unknown key: {keyRef}");
+                throw new ArgumentException($"key error: unknown key '{keyRef}'");
             return key;
         }
 
@@ -321,7 +332,7 @@ private void LoadKeys(JsonElement root)
                 }
                 else
                 {
-                    throw new ArgumentException($"Key '{name}' must have either 'material' or 'source'");
+                    throw new ArgumentException($"key error: key '{name}' must have either 'material' or 'source'");
                 }
             }
         }
@@ -372,12 +383,12 @@ private void LoadConfigurations(JsonElement root)
                 string? header = p.TryGetProperty("header", out var hv) ? hv.GetString() : null;
 
                 if (headerEnabled && string.IsNullOrEmpty(header))
-                    throw new ArgumentException($"Configuration '{kv.Name}' has header_enabled=true but no header specified");
+                    throw new ArgumentException("configuration error: header must be specified");
 
                 if (headerEnabled && header != null)
                 {
                     if (_headerIndex.ContainsKey(header))
-                        throw new ArgumentException($"Header collision: '{header}' used by both '{_headerIndex[header]}' and '{kv.Name}'");
+                        throw new ArgumentException("configuration error: header collision");
                     _headerIndex[header] = kv.Name;
                 }
 
diff --git a/src/Cyphera/FF1.cs b/src/Cyphera/FF1.cs
@@ -15,7 +15,7 @@ public class FF1
         public FF1(byte[] key, byte[] tweak, string alphabet = "0123456789abcdefghijklmnopqrstuvwxyz")
         {
             if (key.Length != 16 && key.Length != 24 && key.Length != 32)
-                throw new ArgumentException("Key must be 16, 24, or 32 bytes");
+                throw new ArgumentException($"invalid key length: {key.Length} (expected 16, 24, or 32)");
             if (alphabet.Length < 2)
                 throw new ArgumentException("Alphabet must have >= 2 chars");
 
@@ -30,7 +30,17 @@ public FF1(byte[] key, byte[] tweak, string alphabet = "0123456789abcdefghijklmn
         public string Encrypt(string plaintext) => FromDigits(FF1Encrypt(ToDigits(plaintext), _tweak));
         public string Decrypt(string ciphertext) => FromDigits(FF1Decrypt(ToDigits(ciphertext), _tweak));
 
-        private int[] ToDigits(string s) => s.Select(c => _charMap[c]).ToArray();
+        private int[] ToDigits(string s)
+        {
+            var d = new int[s.Length];
+            for (int i = 0; i < s.Length; i++)
+            {
+                if (!_charMap.TryGetValue(s[i], out var idx))
+                    throw new ArgumentException($"invalid char '{s[i]}' at position {i}");
+                d[i] = idx;
+            }
+            return d;
+        }
         private string FromDigits(int[] d) => new string(d.Select(i => _alphabet[i]).ToArray());
 
         // NIST SP 800-38G: length >= 2 and radix^length >= 1,000,000.
diff --git a/src/Cyphera/FF3.cs b/src/Cyphera/FF3.cs
@@ -15,9 +15,9 @@ public class FF3
         public FF3(byte[] key, byte[] tweak, string alphabet = "0123456789abcdefghijklmnopqrstuvwxyz")
         {
             if (key.Length != 16 && key.Length != 24 && key.Length != 32)
-                throw new ArgumentException("Key must be 16, 24, or 32 bytes");
+                throw new ArgumentException($"invalid key length: {key.Length} (expected 16, 24, or 32)");
             if (tweak.Length != 8)
-                throw new ArgumentException("Tweak must be exactly 8 bytes");
+                throw new ArgumentException($"invalid tweak length: {tweak.Length} (expected 8)");
             if (alphabet.Length < 2)
                 throw new ArgumentException("Alphabet must have >= 2 chars");
 
@@ -32,7 +32,17 @@ public FF3(byte[] key, byte[] tweak, string alphabet = "0123456789abcdefghijklmn
         public string Encrypt(string plaintext) => FromDigits(FF3Encrypt(ToDigits(plaintext)));
         public string Decrypt(string ciphertext) => FromDigits(FF3Decrypt(ToDigits(ciphertext)));
 
-        private int[] ToDigits(string s) => s.Select(c => _charMap[c]).ToArray();
+        private int[] ToDigits(string s)
+        {
+            var d = new int[s.Length];
+            for (int i = 0; i < s.Length; i++)
+            {
+                if (!_charMap.TryGetValue(s[i], out var idx))
+                    throw new ArgumentException($"invalid char '{s[i]}' at position {i}");
+                d[i] = idx;
+            }
+            return d;
+        }
         private string FromDigits(int[] d) => new string(d.Select(i => _alphabet[i]).ToArray());
 
         // NIST SP 800-38G: length >= 2, radix^length >= 1,000,000, and
@@ -175,7 +185,7 @@ public class FF31
         public FF31(byte[] key, byte[] tweak, string alphabet = "0123456789abcdefghijklmnopqrstuvwxyz")
         {
             if (tweak.Length != 7)
-                throw new ArgumentException("FF3-1 tweak must be exactly 7 bytes (56 bits)");
+                throw new ArgumentException($"invalid tweak length: {tweak.Length} (expected 7)");
             _inner = new FF3(key, ExpandTweak(tweak), alphabet);
         }
 
diff --git a/tests/Cyphera.Tests/CypheraClientTests.cs b/tests/Cyphera.Tests/CypheraClientTests.cs
@@ -91,7 +91,7 @@ public void AccessNonreversibleRaises()
             // ssn_mask has header_enabled=false, so Access() can't find a header
             // and reports the no-matching-header error.
             var ex = Assert.Throws<ArgumentException>(() => c.Access(masked));
-            Assert.Contains("No matching header", ex.Message);
+            Assert.Equal("no matching header found", ex.Message);
         }
 
         [Fact]
@@ -106,7 +106,7 @@ public void HeaderCollisionRaises()
             }";
             var doc = JsonDocument.Parse(json);
             var ex = Assert.Throws<ArgumentException>(() => Cyphera.FromConfig(doc.RootElement));
-            Assert.Contains("Header collision", ex.Message);
+            Assert.Equal("configuration error: header collision", ex.Message);
         }
 
         [Fact]
@@ -118,7 +118,7 @@ public void HeaderRequiredRaises()
             }";
             var doc = JsonDocument.Parse(json);
             var ex = Assert.Throws<ArgumentException>(() => Cyphera.FromConfig(doc.RootElement));
-            Assert.Contains("no header specified", ex.Message);
+            Assert.Equal("configuration error: header must be specified", ex.Message);
         }
 
         [Fact]
@@ -148,7 +148,8 @@ public void TwoArgAccessOnIrreversibleConfigRaises()
             // The 2-arg escape hatch is permissive about header_enabled but
             // still must refuse mask/hash configurations — those are one-way.
             var masked = c.Protect("123-45-6789", "ssn_mask");
-            Assert.Throws<ArgumentException>(() => c.Access(masked, "ssn_mask"));
+            var ex = Assert.Throws<ArgumentException>(() => c.Access(masked, "ssn_mask"));
+            Assert.Equal("cannot reverse 'ssn_mask' — mask is irreversible", ex.Message);
         }
     }
 }

Original file line number	Diff line number	Diff line change
`@@ -66,7 +66,7 @@ public string Protect(string value, string configurationName)`
`66`	`66`	`"ff1" or "ff3" or "ff31" => ProtectFpe(value, configuration),`
`67`	`67`	`"mask" => ProtectMask(value, configuration),`
`68`	`68`	`"hash" => ProtectHash(value, configuration),`
`69`		`- _ => throw new ArgumentException($"Unknown engine: {configuration.Engine}")`
	`69`	`+ _ => throw new ArgumentException($"unknown engine: {configuration.Engine}")`
`70`	`70`	`};`
`71`	`71`	`}`
`72`	`72`
`@@ -80,14 +80,15 @@ public string Access(string protectedValue)`
`80`	`80`	`{`
`81`	`81`	`if (protectedValue.Length > header.Length && protectedValue.StartsWith(header))`
`82`	`82`	`{`
`83`		`- var configuration = GetConfiguration(_headerIndex[header]);`
	`83`	`+ var name = _headerIndex[header];`
	`84`	`+ var configuration = GetConfiguration(name);`
`84`	`85`	`// Strip the header here so AccessFpe always receives raw headerless ciphertext.`
`85`	`86`	`var stripped = protectedValue[header.Length..];`
`86`		`- return AccessFpe(stripped, configuration);`
	`87`	`+ return AccessWithConfiguration(stripped, configuration, name);`
`87`	`88`	`}`
`88`	`89`	`}`
`89`	`90`
`90`		`- throw new ArgumentException("No matching header found");`
	`91`	`+ throw new ArgumentException("no matching header found");`
`91`	`92`	`}`
`92`	`93`
`93`	`94`	`// Escape-hatch access for unique situations where the protected value`
`@@ -102,6 +103,14 @@ public string Access(string protectedValue, string configurationName)`
`102`	`103`	`if (configurationName == null)`
`103`	`104`	`throw new ArgumentException("Access(value, configurationName) requires a configuration name.");`
`104`	`105`	`var configuration = GetConfiguration(configurationName);`
	`106`	`+ return AccessWithConfiguration(protectedValue, configuration, configurationName);`
	`107`	`+ }`
	`108`	`+`
	`109`	`+ private string AccessWithConfiguration(string protectedValue, Configuration configuration, string configurationName)`
	`110`	`+ {`
	`111`	`+ if (configuration.Engine == "mask" \|\| configuration.Engine == "hash")`
	`112`	`+ throw new ArgumentException(`
	`113`	`+ $"cannot reverse '{configurationName}' — {configuration.Engine} is irreversible");`
`105`	`114`	`return AccessFpe(protectedValue, configuration);`
`106`	`115`	`}`
`107`	`116`
`@@ -131,7 +140,7 @@ private string ProtectFpe(string value, Configuration configuration)`
`131`	`140`
`132`	`141`	`var (encryptable, positions, chars) = ExtractPassthroughs(value, alphabet);`
`133`	`142`	`if (encryptable.Length == 0)`
`134`		`- throw new ArgumentException("No encryptable characters in input");`
	`143`	`+ throw new ArgumentException("no encryptable characters in input");`
`135`	`144`
`136`	`145`	`string encrypted;`
`137`	`146`	`if (configuration.Engine == "ff3")`
`@@ -164,8 +173,10 @@ private string ProtectFpe(string value, Configuration configuration)`
`164`	`173`	`// a headerless value.`
`165`	`174`	`private string AccessFpe(string protectedValue, Configuration configuration)`
`166`	`175`	`{`
	`176`	`+ // Callers (AccessWithConfiguration) have already filtered mask/hash;`
	`177`	`+ // anything else here that isn't an FPE engine is an internal misuse.`
`167`	`178`	`if (configuration.Engine != "ff1" && configuration.Engine != "ff3" && configuration.Engine != "ff31")`
`168`		`- throw new ArgumentException($"Cannot reverse '{configuration.Engine}' — not reversible");`
	`179`	`+ throw new ArgumentException($"unknown engine: {configuration.Engine}");`
`169`	`180`
`170`	`181`	`var key = ResolveKey(configuration.KeyRef);`
`171`	`182`	`var alphabet = configuration.Alphabet;`
`@@ -198,7 +209,7 @@ private string AccessFpe(string protectedValue, Configuration configuration)`
`198`	`209`	`private static string ProtectMask(string value, Configuration configuration)`
`199`	`210`	`{`
`200`	`211`	`if (string.IsNullOrEmpty(configuration.Pattern))`
`201`		`- throw new ArgumentException("Mask configuration requires 'pattern'");`
	`212`	`+ throw new ArgumentException("mask pattern required");`
`202`	`213`
`203`	`214`	`int len = value.Length;`
`204`	`215`	`return configuration.Pattern switch`
`@@ -248,16 +259,16 @@ private string ProtectHash(string value, Configuration configuration)`
`248`	`259`	`private Configuration GetConfiguration(string name)`
`249`	`260`	`{`
`250`	`261`	`if (!_configurations.TryGetValue(name, out var configuration))`
`251`		`- throw new ArgumentException($"Unknown configuration: {name}");`
	`262`	`+ throw new ArgumentException($"configuration not found: {name}");`
`252`	`263`	`return configuration;`
`253`	`264`	`}`
`254`	`265`
`255`	`266`	`private byte[] ResolveKey(string? keyRef)`
`256`	`267`	`{`
`257`	`268`	`if (string.IsNullOrEmpty(keyRef))`
`258`		`- throw new ArgumentException("No key_ref in configuration");`
	`269`	`+ throw new ArgumentException("key error: no key_ref in configuration");`
`259`	`270`	`if (!_keys.TryGetValue(keyRef, out var key))`
`260`		`- throw new ArgumentException($"Unknown key: {keyRef}");`
	`271`	`+ throw new ArgumentException($"key error: unknown key '{keyRef}'");`
`261`	`272`	`return key;`
`262`	`273`	`}`
`263`	`274`
`@@ -321,7 +332,7 @@ private void LoadKeys(JsonElement root)`
`321`	`332`	`}`
`322`	`333`	`else`
`323`	`334`	`{`
`324`		`- throw new ArgumentException($"Key '{name}' must have either 'material' or 'source'");`
	`335`	`+ throw new ArgumentException($"key error: key '{name}' must have either 'material' or 'source'");`
`325`	`336`	`}`
`326`	`337`	`}`
`327`	`338`	`}`
`@@ -372,12 +383,12 @@ private void LoadConfigurations(JsonElement root)`
`372`	`383`	`string? header = p.TryGetProperty("header", out var hv) ? hv.GetString() : null;`
`373`	`384`
`374`	`385`	`if (headerEnabled && string.IsNullOrEmpty(header))`
`375`		`- throw new ArgumentException($"Configuration '{kv.Name}' has header_enabled=true but no header specified");`
	`386`	`+ throw new ArgumentException("configuration error: header must be specified");`
`376`	`387`
`377`	`388`	`if (headerEnabled && header != null)`
`378`	`389`	`{`
`379`	`390`	`if (_headerIndex.ContainsKey(header))`
`380`		`- throw new ArgumentException($"Header collision: '{header}' used by both '{_headerIndex[header]}' and '{kv.Name}'");`
	`391`	`+ throw new ArgumentException("configuration error: header collision");`
`381`	`392`	`_headerIndex[header] = kv.Name;`
`382`	`393`	`}`
`383`	`394`
Original file line number	Diff line number	Diff line change
`@@ -91,7 +91,7 @@ public void AccessNonreversibleRaises()`
`91`	`91`	`// ssn_mask has header_enabled=false, so Access() can't find a header`
`92`	`92`	`// and reports the no-matching-header error.`
`93`	`93`	`var ex = Assert.Throws<ArgumentException>(() => c.Access(masked));`
`94`		`- Assert.Contains("No matching header", ex.Message);`
	`94`	`+ Assert.Equal("no matching header found", ex.Message);`
`95`	`95`	`}`
`96`	`96`
`97`	`97`	`[Fact]`
`@@ -106,7 +106,7 @@ public void HeaderCollisionRaises()`
`106`	`106`	`}";`
`107`	`107`	`var doc = JsonDocument.Parse(json);`
`108`	`108`	`var ex = Assert.Throws<ArgumentException>(() => Cyphera.FromConfig(doc.RootElement));`
`109`		`- Assert.Contains("Header collision", ex.Message);`
	`109`	`+ Assert.Equal("configuration error: header collision", ex.Message);`
`110`	`110`	`}`
`111`	`111`
`112`	`112`	`[Fact]`
`@@ -118,7 +118,7 @@ public void HeaderRequiredRaises()`
`118`	`118`	`}";`
`119`	`119`	`var doc = JsonDocument.Parse(json);`
`120`	`120`	`var ex = Assert.Throws<ArgumentException>(() => Cyphera.FromConfig(doc.RootElement));`
`121`		`- Assert.Contains("no header specified", ex.Message);`
	`121`	`+ Assert.Equal("configuration error: header must be specified", ex.Message);`
`122`	`122`	`}`
`123`	`123`
`124`	`124`	`[Fact]`
`@@ -148,7 +148,8 @@ public void TwoArgAccessOnIrreversibleConfigRaises()`
`148`	`148`	`// The 2-arg escape hatch is permissive about header_enabled but`
`149`	`149`	`// still must refuse mask/hash configurations — those are one-way.`
`150`	`150`	`var masked = c.Protect("123-45-6789", "ssn_mask");`
`151`		`- Assert.Throws<ArgumentException>(() => c.Access(masked, "ssn_mask"));`
	`151`	`+ var ex = Assert.Throws<ArgumentException>(() => c.Access(masked, "ssn_mask"));`
	`152`	`+ Assert.Equal("cannot reverse 'ssn_mask' — mask is irreversible", ex.Message);`
`152`	`153`	`}`
`153`	`154`	`}`
`154`	`155`	`}`