Skip to content

Commit d7dbfe6

Browse files
committed
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 skipped header stripping on the explicit-configuration path, which made the API ambiguous (callers couldn't tell whether the value they passed had a header or not) and returned garbage when called on a headered config. Now it errors out cleanly with a ValueError so callers can fix the call site instead of seeing wrong decrypts. Implementation: access(value, name) now checks header_enabled on the named configuration and raises ValueError if true. The header-based access(value) path strips the header itself before delegating to _access_fpe, so _access_fpe always assumes raw headerless input and the explicit_configuration flag is gone. Added one error-condition test; existing 2-arg tests already used header_enabled=False configs so no test rewrites were needed. 42 tests pass.
1 parent e36a148 commit d7dbfe6

2 files changed

Lines changed: 24 additions & 9 deletions

File tree

‎cyphera/sdk.py‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -148,13 +148,20 @@ def protect(self, value: str, configuration_name: str) -> str:
148148
def access(self, protected_value: str, configuration_name: str = None) -> str:
149149
if configuration_name:
150150
configuration = self._get_configuration(configuration_name)
151-
return self._access_fpe(protected_value, configuration, explicit_configuration=True)
151+
if configuration["header_enabled"]:
152+
raise ValueError(
153+
f"configuration '{configuration_name}' has header_enabled=True; "
154+
"use access(value) — the header identifies the configuration. "
155+
"The two-arg form is for header_enabled=False configurations only."
156+
)
157+
return self._access_fpe(protected_value, configuration)
152158

153159
# Header-based lookup — longest headers first
154160
for header in sorted(self._header_index.keys(), key=len, reverse=True):
155161
if protected_value.startswith(header):
156162
configuration = self._get_configuration(self._header_index[header])
157-
return self._access_fpe(protected_value, configuration)
163+
# Strip the header before delegating; _access_fpe always assumes raw input.
164+
return self._access_fpe(protected_value[len(header):], configuration)
158165

159166
raise ValueError("No matching header found. Use access(value, configuration_name) for headerless values.")
160167

@@ -185,20 +192,20 @@ def _protect_fpe(self, value: str, configuration: dict, is_ff3: bool) -> str:
185192
return configuration["header"] + result
186193
return result
187194

188-
def _access_fpe(self, protected_value: str, configuration: dict, explicit_configuration: bool = False) -> str:
195+
def _access_fpe(self, protected_value: str, configuration: dict) -> str:
196+
"""Internal: decrypt assuming `protected_value` is already header-stripped.
197+
198+
Used by `access(value)` (which strips the header itself) and by
199+
`access(value, name)` (only valid for header_enabled=False configs).
200+
"""
189201
if configuration["engine"] not in ("ff1", "ff3"):
190202
raise ValueError(f"Cannot reverse '{configuration['engine']}' — not reversible")
191203

192204
key = self._resolve_key(configuration["key_ref"])
193205
alphabet = configuration["alphabet"]
194206

195-
# Strip header (only when auto-detected, not when configuration explicitly provided)
196-
without_header = protected_value
197-
if not explicit_configuration and configuration["header_enabled"] and configuration["header"]:
198-
without_header = protected_value[len(configuration["header"]):]
199-
200207
# Strip passthroughs
201-
encryptable, positions, chars = self._extract_passthroughs(without_header, alphabet)
208+
encryptable, positions, chars = self._extract_passthroughs(protected_value, alphabet)
202209

203210
# Decrypt
204211
if configuration["engine"] == "ff3":

‎tests/test_sdk.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,14 @@ def test_access_nonreversible_raises():
6969
c.access(masked)
7070

7171

72+
def test_access_two_arg_on_headered_config_raises():
73+
c = Cyphera(CONFIG)
74+
protected = c.protect("123456789", "ssn")
75+
# ssn has header_enabled=True; calling access(value, name) must error.
76+
with pytest.raises(ValueError, match="header_enabled=True"):
77+
c.access(protected, "ssn")
78+
79+
7280
def test_header_collision_raises():
7381
with pytest.raises(ValueError, match="Header collision"):
7482
Cyphera({

0 commit comments

Comments
 (0)