ranbval-sdk 2.2.0__tar.gz → 2.3.0__tar.gz

{ranbval_sdk-2.2.0 → ranbval_sdk-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ranbval-sdk
-Version: 2.2.0
+Version: 2.3.0
 Summary: Keep API secrets out of plaintext config: layered .ranbval* env files, decrypt vault tokens only when used, with built-in repo-allowlist enforcement and automatic usage telemetry to the Live Monitor—minimal deps, your own HTTP/SDK stack.
 License-Expression: MIT
 License-File: LICENSE
@@ -24,7 +24,7 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/pypi/pyversions/ranbval-sdk)](https://pypi.org/project/ranbval-sdk/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-# Ranbval SDK `v2.2.0`
+# Ranbval SDK `v2.2.1`
 
 **The Python client for Ranbval — a secret manager for API keys.** Encrypt secrets in the
 Ranbval dashboard, store the encrypted tokens in `.ranbval` files, and decrypt them only at
@@ -138,6 +138,9 @@ OPENAI_API_KEY=ranbval.4ii0a022aa.p1GOZ...ahsan
 | `safe_decrypt()` | Decrypts a vault token string → `SecretString` |
 | `decrypt_key()` | Reads an env var and decrypts it in one call |
 | `SecretString` | Wrapper that blocks all display paths — value only via `.use()` |
+| `require_reveal_scope()` / `reveal_scope()` | Restrict a secret so `.use()` works only inside an approved block |
+| `install_access_monitor()` | Detect & report suspicious secret access / possible exfiltration |
+| `set_enforcement()` / `is_enforced()` | Toggle strict mode — extraction attempts raise `RanbvalSecurityError` (on by default) |
 | `proxy_request()` | Route an HTTP request through the Ranbval proxy (key injected server-side) |
 | `emit_telemetry()` | Record a **custom** usage event (basic usage is auto-reported on every `decrypt_key()`) |
 | `get_audit_log()` | Return the in-process audit log list |
@@ -512,6 +515,25 @@ clear_audit_log()
 assert get_audit_log() == []
 ```
 
+`audit_scope()` captures just the accesses inside a `with` block (handy for tests): `with audit_scope() as accesses: ...` then inspect `accesses`. `install_access_monitor()` / `uninstall_access_monitor()` turn live suspicious-access detection on and off (see [Trusted-party controls](#trusted-party-controls-restrict--detect)).
+
+---
+
+## Exceptions
+
+Every error derives from `RanbvalError`; each also subclasses the built-in it replaces, so existing `except ValueError` / `except KeyError` / `except PermissionError` code keeps working. Each carries a machine-readable `.code` and a `.context` dict.
+
+| Exception | Also a | Raised when |
+|---|---|---|
+| `RanbvalDecryptError` | `ValueError` | wrong project secret, corrupt/expired token |
+| `RanbvalConfigError` | `ValueError` | env var/secret missing, wrong section (`proxy_only`, `not_a_public_key`, `reveal_out_of_scope`) |
+| `MissingKeyError` | `KeyError` | attribute/item access to an absent key |
+| `RepoNotAllowedError` | `PermissionError` | git remote not in the project allowlist |
+| `RepoPolicyError` | `PermissionError` | repo policy couldn't be loaded/verified |
+| `ProxyError` | `RuntimeError` | the secure proxy rejected the request or was unreachable |
+
+The `SecretProvider` protocol types anything that can `reveal(name) -> str` (e.g. `Vault`).
+
 ---
 
 ## Three sections: `[public]` · `[secrets]` · `[proxy]`
@@ -594,6 +616,114 @@ env.public("OPENAI_API_KEY")   # -> raises (declared [proxy]) — use proxy_requ
 
 ---
 
+## Trusted-party controls: restrict & detect
+
+For a value your app **must** decrypt locally (a DB password, a signing key) but that you don't
+want an engineer to read from anywhere but one approved place. Once plaintext exists in a
+process, in-process code can always reach it — so these tools **restrict** where it's revealed
+and **detect** attempts, rather than promising the impossible ("hide it from your own code").
+
+### Reveal scopes — `.use()` only at the approved line
+
+```python
+from ranbval_sdk import require_reveal_scope, reveal_scope, decrypt_key
+
+require_reveal_scope("DATABASE_PASSWORD")          # once, at startup
+
+# The ONLY place its plaintext may be produced:
+with reveal_scope("DATABASE_PASSWORD"):
+    conn = psycopg2.connect(password=decrypt_key("DATABASE_PASSWORD").use())
+
+# Anywhere else — an engineer can't extract it:
+decrypt_key("DATABASE_PASSWORD").use()
+# → RanbvalConfigError: may only be revealed inside `with reveal_scope("DATABASE_PASSWORD")`
+```
+
+`reveal_scope("NAME")` becomes an explicit, greppable marker you can enforce in CI ("this token
+must appear in exactly one file"). It is thread-local — a scope open on one thread never permits
+a reveal on another.
+
+### Enforcement — extraction attempts raise (strict by default)
+
+As of **2.3.0**, the naive in-memory extraction vectors don't just get reported — they **raise
+`RanbvalSecurityError`**, so a script trying to steal the value fails loudly instead of walking
+off with it:
+
+```python
+key = decrypt_key("OPENAI_API_KEY")
+val = key.use()
+
+client = OpenAI(api_key=key.use())    # ✅ correct — pass it straight in
+f"Bearer {val}"                        # ✅ works (SDK header building)
+"Bearer " + val                        # ✅ works (concatenation)
+
+"".join(c for c in val)                # ❌ RanbvalSecurityError (iteration)
+val.encode()                           # ❌ RanbvalSecurityError (encode)
+val[:]  /  val[0]                       # ❌ RanbvalSecurityError (slice / index)
+str(val)  /  print(val)  /  "%s" % val  # ❌ RanbvalSecurityError (str/display)
+some_secret._buf                       # ❌ RanbvalSecurityError (buffer read)
+object.__getattribute__(s, "_buf")     # ❌ RanbvalSecurityError (honeypot property)
+```
+
+> `str(val)` **raises** under enforcement (loud) instead of returning `[ranbval:secret]`; with
+> `set_enforcement(False)` it masks as before. `repr(val)` always stays masked (so error
+> reporters and debuggers don't crash).
+
+If a legitimate library trips it (an AWS SigV4 signer or a DB driver that must `.encode()` the
+credential), turn enforcement off process-wide:
+
+```python
+from ranbval_sdk import set_enforcement
+set_enforcement(False)   # back to detect + notify (value returned, event still fires)
+```
+
+### Access monitor — detect suspicious access / exfiltration
+
+With enforcement **off**, the same vectors are *detected and reported* instead of blocked (and
+the access monitor always adds context — REPL use, file-write correlation — regardless):
+
+```python
+from ranbval_sdk import install_access_monitor
+
+install_access_monitor()                    # signals go to the Live Monitor
+# or handle them yourself:
+install_access_monitor(on_event=lambda e: log.warning("secret access", **e))
+```
+
+It fires an event when a secret is accessed or manipulated in a way that signals extraction:
+
+| Signal | Fires when | Enforced (raises)? |
+|---|---|---|
+| `secret.suspicious_access` | `.use()` from `python -c` / a REPL / a notebook (not your app) | no — reported only |
+| `secret.possible_exfil` (`iteration`) | `''.join(ch for ch in key.use())` / `list(...)` / a comprehension | **yes** |
+| `secret.possible_exfil` (`encode`) | `key.use().encode()` | **yes** |
+| `secret.possible_exfil` (`slice`) | `val[:]` / `val[0]` / any indexing of a revealed value | **yes** |
+| `secret.possible_exfil` (`buffer_read`) | `s._buf` / `s._pad` — including via `object.__getattribute__` (honeypot properties) | **yes** |
+| `secret.possible_exfil` (`file_write` / `subprocess`) | a file write or subprocess right after a `.use()` | no — reported only |
+
+Nothing legitimate breaks — an SDK never iterates or slices an API key, and f-strings build
+headers through a base-`str` path that is not flagged.
+
+**Honest limit (what still can't be blocked).** Enforcement *raises the bar* — it turns silent
+theft into a loud, alerting crash, and now catches the naive `str()`/`_buf`/slice/iterate
+spellings — but it does **not** make in-process extraction impossible. Two floors remain, and we
+deliberately do **not** fake-guard them:
+
+- **`str.__str__(val)`** (and other base-`str` methods: `str.__getitem__(val, ...)`,
+  `str.encode(val)`, and concatenation `"x" + val`) return the real value. The built-in `str`
+  type is immutable — CPython won't let any library override it — so these cannot be intercepted,
+  and **the SDK depends on them**: `OpenAI(api_key=key.use())` only works because the value *is*
+  a real string that libraries can format/concatenate into a request. A value the SDK can use is
+  a value any in-process code can read. That's the fundamental trade-off, not a missing feature.
+- **`object.__getattribute__(s, "_b")`** still reads the real (XOR-masked) buffer slot. Ranbval
+  is open source, so anyone who reads this file finds the slot name. Renaming it again would only
+  move the same hole.
+
+The one true "value never on the client" answer is the [proxy](#proxy_request) — the real key is
+decrypted server-side and never returned to your process at all.
+
+---
+
 ## `.ranbval` File Format
 
 `.ranbval` files follow the same `KEY=VALUE` format as `.env` files. Lines starting with `#` are comments. Blank lines are ignored. Optional `[public]` / `[secrets]` section headers group keys (see above).

{ranbval_sdk-2.2.0 → ranbval_sdk-2.3.0}/README.md

@@ -2,7 +2,7 @@
 [![Python](https://img.shields.io/pypi/pyversions/ranbval-sdk)](https://pypi.org/project/ranbval-sdk/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-# Ranbval SDK `v2.2.0`
+# Ranbval SDK `v2.2.1`
 
 **The Python client for Ranbval — a secret manager for API keys.** Encrypt secrets in the
 Ranbval dashboard, store the encrypted tokens in `.ranbval` files, and decrypt them only at
@@ -116,6 +116,9 @@ OPENAI_API_KEY=ranbval.4ii0a022aa.p1GOZ...ahsan
 | `safe_decrypt()` | Decrypts a vault token string → `SecretString` |
 | `decrypt_key()` | Reads an env var and decrypts it in one call |
 | `SecretString` | Wrapper that blocks all display paths — value only via `.use()` |
+| `require_reveal_scope()` / `reveal_scope()` | Restrict a secret so `.use()` works only inside an approved block |
+| `install_access_monitor()` | Detect & report suspicious secret access / possible exfiltration |
+| `set_enforcement()` / `is_enforced()` | Toggle strict mode — extraction attempts raise `RanbvalSecurityError` (on by default) |
 | `proxy_request()` | Route an HTTP request through the Ranbval proxy (key injected server-side) |
 | `emit_telemetry()` | Record a **custom** usage event (basic usage is auto-reported on every `decrypt_key()`) |
 | `get_audit_log()` | Return the in-process audit log list |
@@ -490,6 +493,25 @@ clear_audit_log()
 assert get_audit_log() == []
 ```
 
+`audit_scope()` captures just the accesses inside a `with` block (handy for tests): `with audit_scope() as accesses: ...` then inspect `accesses`. `install_access_monitor()` / `uninstall_access_monitor()` turn live suspicious-access detection on and off (see [Trusted-party controls](#trusted-party-controls-restrict--detect)).
+
+---
+
+## Exceptions
+
+Every error derives from `RanbvalError`; each also subclasses the built-in it replaces, so existing `except ValueError` / `except KeyError` / `except PermissionError` code keeps working. Each carries a machine-readable `.code` and a `.context` dict.
+
+| Exception | Also a | Raised when |
+|---|---|---|
+| `RanbvalDecryptError` | `ValueError` | wrong project secret, corrupt/expired token |
+| `RanbvalConfigError` | `ValueError` | env var/secret missing, wrong section (`proxy_only`, `not_a_public_key`, `reveal_out_of_scope`) |
+| `MissingKeyError` | `KeyError` | attribute/item access to an absent key |
+| `RepoNotAllowedError` | `PermissionError` | git remote not in the project allowlist |
+| `RepoPolicyError` | `PermissionError` | repo policy couldn't be loaded/verified |
+| `ProxyError` | `RuntimeError` | the secure proxy rejected the request or was unreachable |
+
+The `SecretProvider` protocol types anything that can `reveal(name) -> str` (e.g. `Vault`).
+
 ---
 
 ## Three sections: `[public]` · `[secrets]` · `[proxy]`
@@ -572,6 +594,114 @@ env.public("OPENAI_API_KEY")   # -> raises (declared [proxy]) — use proxy_requ
 
 ---
 
+## Trusted-party controls: restrict & detect
+
+For a value your app **must** decrypt locally (a DB password, a signing key) but that you don't
+want an engineer to read from anywhere but one approved place. Once plaintext exists in a
+process, in-process code can always reach it — so these tools **restrict** where it's revealed
+and **detect** attempts, rather than promising the impossible ("hide it from your own code").
+
+### Reveal scopes — `.use()` only at the approved line
+
+```python
+from ranbval_sdk import require_reveal_scope, reveal_scope, decrypt_key
+
+require_reveal_scope("DATABASE_PASSWORD")          # once, at startup
+
+# The ONLY place its plaintext may be produced:
+with reveal_scope("DATABASE_PASSWORD"):
+    conn = psycopg2.connect(password=decrypt_key("DATABASE_PASSWORD").use())
+
+# Anywhere else — an engineer can't extract it:
+decrypt_key("DATABASE_PASSWORD").use()
+# → RanbvalConfigError: may only be revealed inside `with reveal_scope("DATABASE_PASSWORD")`
+```
+
+`reveal_scope("NAME")` becomes an explicit, greppable marker you can enforce in CI ("this token
+must appear in exactly one file"). It is thread-local — a scope open on one thread never permits
+a reveal on another.
+
+### Enforcement — extraction attempts raise (strict by default)
+
+As of **2.3.0**, the naive in-memory extraction vectors don't just get reported — they **raise
+`RanbvalSecurityError`**, so a script trying to steal the value fails loudly instead of walking
+off with it:
+
+```python
+key = decrypt_key("OPENAI_API_KEY")
+val = key.use()
+
+client = OpenAI(api_key=key.use())    # ✅ correct — pass it straight in
+f"Bearer {val}"                        # ✅ works (SDK header building)
+"Bearer " + val                        # ✅ works (concatenation)
+
+"".join(c for c in val)                # ❌ RanbvalSecurityError (iteration)
+val.encode()                           # ❌ RanbvalSecurityError (encode)
+val[:]  /  val[0]                       # ❌ RanbvalSecurityError (slice / index)
+str(val)  /  print(val)  /  "%s" % val  # ❌ RanbvalSecurityError (str/display)
+some_secret._buf                       # ❌ RanbvalSecurityError (buffer read)
+object.__getattribute__(s, "_buf")     # ❌ RanbvalSecurityError (honeypot property)
+```
+
+> `str(val)` **raises** under enforcement (loud) instead of returning `[ranbval:secret]`; with
+> `set_enforcement(False)` it masks as before. `repr(val)` always stays masked (so error
+> reporters and debuggers don't crash).
+
+If a legitimate library trips it (an AWS SigV4 signer or a DB driver that must `.encode()` the
+credential), turn enforcement off process-wide:
+
+```python
+from ranbval_sdk import set_enforcement
+set_enforcement(False)   # back to detect + notify (value returned, event still fires)
+```
+
+### Access monitor — detect suspicious access / exfiltration
+
+With enforcement **off**, the same vectors are *detected and reported* instead of blocked (and
+the access monitor always adds context — REPL use, file-write correlation — regardless):
+
+```python
+from ranbval_sdk import install_access_monitor
+
+install_access_monitor()                    # signals go to the Live Monitor
+# or handle them yourself:
+install_access_monitor(on_event=lambda e: log.warning("secret access", **e))
+```
+
+It fires an event when a secret is accessed or manipulated in a way that signals extraction:
+
+| Signal | Fires when | Enforced (raises)? |
+|---|---|---|
+| `secret.suspicious_access` | `.use()` from `python -c` / a REPL / a notebook (not your app) | no — reported only |
+| `secret.possible_exfil` (`iteration`) | `''.join(ch for ch in key.use())` / `list(...)` / a comprehension | **yes** |
+| `secret.possible_exfil` (`encode`) | `key.use().encode()` | **yes** |
+| `secret.possible_exfil` (`slice`) | `val[:]` / `val[0]` / any indexing of a revealed value | **yes** |
+| `secret.possible_exfil` (`buffer_read`) | `s._buf` / `s._pad` — including via `object.__getattribute__` (honeypot properties) | **yes** |
+| `secret.possible_exfil` (`file_write` / `subprocess`) | a file write or subprocess right after a `.use()` | no — reported only |
+
+Nothing legitimate breaks — an SDK never iterates or slices an API key, and f-strings build
+headers through a base-`str` path that is not flagged.
+
+**Honest limit (what still can't be blocked).** Enforcement *raises the bar* — it turns silent
+theft into a loud, alerting crash, and now catches the naive `str()`/`_buf`/slice/iterate
+spellings — but it does **not** make in-process extraction impossible. Two floors remain, and we
+deliberately do **not** fake-guard them:
+
+- **`str.__str__(val)`** (and other base-`str` methods: `str.__getitem__(val, ...)`,
+  `str.encode(val)`, and concatenation `"x" + val`) return the real value. The built-in `str`
+  type is immutable — CPython won't let any library override it — so these cannot be intercepted,
+  and **the SDK depends on them**: `OpenAI(api_key=key.use())` only works because the value *is*
+  a real string that libraries can format/concatenate into a request. A value the SDK can use is
+  a value any in-process code can read. That's the fundamental trade-off, not a missing feature.
+- **`object.__getattribute__(s, "_b")`** still reads the real (XOR-masked) buffer slot. Ranbval
+  is open source, so anyone who reads this file finds the slot name. Renaming it again would only
+  move the same hole.
+
+The one true "value never on the client" answer is the [proxy](#proxy_request) — the real key is
+decrypted server-side and never returned to your process at all.
+
+---
+
 ## `.ranbval` File Format
 
 `.ranbval` files follow the same `KEY=VALUE` format as `.env` files. Lines starting with `#` are comments. Blank lines are ignored. Optional `[public]` / `[secrets]` section headers group keys (see above).

{ranbval_sdk-2.2.0 → ranbval_sdk-2.3.0}/pyproject.toml

@@ -2,7 +2,7 @@
 # [tool.poetry] block below only carries build-time bits that have no PEP 621 field.
 [project]
 name = "ranbval-sdk"
-version = "2.2.0"
+version = "2.3.0"
 description = "Keep API secrets out of plaintext config: layered .ranbval* env files, decrypt vault tokens only when used, with built-in repo-allowlist enforcement and automatic usage telemetry to the Live Monitor—minimal deps, your own HTTP/SDK stack."
 authors = [
     { name = "Ahsan Tariq" },

{ranbval_sdk-2.2.0 → ranbval_sdk-2.3.0}/src/ranbval_sdk/__init__.py

@@ -52,7 +52,9 @@ from ranbval_sdk.crypto import (
     clear_audit_log,
     decrypt_key,
     get_audit_log,
+    is_enforced,
     safe_decrypt,
+    set_enforcement,
 )
 from ranbval_sdk.exceptions import (
     MissingKeyError,
@@ -60,6 +62,7 @@ from ranbval_sdk.exceptions import (
     RanbvalConfigError,
     RanbvalDecryptError,
     RanbvalError,
+    RanbvalSecurityError,
     RepoNotAllowedError,
     RepoPolicyError,
 )
@@ -73,7 +76,7 @@ from ranbval_sdk.telemetry import (
     uninstall_access_monitor,
 )
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 
 __all__ = [
     # Config
@@ -102,6 +105,8 @@ __all__ = [
     "safe_decrypt",
     "decrypt_key",
     "SecretString",
+    "set_enforcement",
+    "is_enforced",
     "get_audit_log",
     "clear_audit_log",
     "audit_scope",
@@ -123,4 +128,5 @@ __all__ = [
     "RepoNotAllowedError",
     "RepoPolicyError",
     "ProxyError",
+    "RanbvalSecurityError",
 ]

{ranbval_sdk-2.2.0 → ranbval_sdk-2.3.0}/src/ranbval_sdk/crypto/__init__.py

@@ -12,7 +12,12 @@ from ranbval_sdk.crypto.audit import (
     record_access,
 )
 from ranbval_sdk.crypto.cipher import decrypt_key, derive_key, safe_decrypt
-from ranbval_sdk.crypto.secret_string import SecretString, install_output_guards
+from ranbval_sdk.crypto.secret_string import (
+    SecretString,
+    install_output_guards,
+    is_enforced,
+    set_enforcement,
+)
 
 __all__ = [
     "safe_decrypt",
@@ -20,6 +25,8 @@ __all__ = [
     "derive_key",
     "SecretString",
     "install_output_guards",
+    "set_enforcement",
+    "is_enforced",
     "get_audit_log",
     "clear_audit_log",
     "audit_scope",

{ranbval_sdk-2.2.0 → ranbval_sdk-2.3.0}/src/ranbval_sdk/crypto/cipher.py

@@ -61,7 +61,10 @@ def derive_key(password: str, salt_str: str) -> bytes:
         salt=salt,
         iterations=PBKDF2_ITERATIONS,
     )
-    return kdf.derive(password.encode())
+    # The project secret arrives as a _ProtectedStr (from get_project_key → .use()). Call the
+    # base str.encode directly so this SDK-internal key derivation is not tripped by extraction
+    # enforcement — same deliberate-internal-read pattern the value type uses elsewhere.
+    return kdf.derive(str.encode(password))
 
 
 def _enforce_repo_allowlist_if_configured(client_salt: str) -> None:

{ranbval_sdk-2.2.0 → ranbval_sdk-2.3.0}/src/ranbval_sdk/crypto/secret_string.py

@@ -27,10 +27,13 @@ as a sealed ``SecretString`` in your code, and every display path above is maske
 
 Honest limits (a security library must not over-promise)
 --------------------------------------------------------
-- ``.use()`` returns a **real ``str``** so third-party SDKs can build headers with it. That
-  means the plaintext genuinely exists in the string — ``secret.use()[:]`` or
-  ``print(f"{secret.use()}")`` will reveal it. That is *deliberate* bypassing, not the
-  accidental leak this guards; anything the SDK can read to build a request, code can read too.
+- ``.use()`` returns a **real ``str``** so third-party SDKs can build headers with it. Under
+  enforcement (the default) the naive extraction spellings raise — iteration, ``.encode()``,
+  ``val[:]`` / indexing, and ``_buf``/``_pad`` reads (see ``set_enforcement``). But the plaintext
+  genuinely exists in the string, so the **base** ``str`` methods still reach it —
+  ``str.__str__(val)`` and ``str.__getitem__(val, ...)`` cannot be blocked (the ``str`` type is
+  immutable) and ``object.__getattribute__(s, "_b")`` reads the real slot. This is bar-raising,
+  not absolute; anything the SDK can read to build a request, determined code can read too.
 - "Zeroing" and ``mlock`` are **best-effort defence-in-depth, not guarantees.** In a managed
   runtime (CPython) the interpreter and the SDK make immutable ``str``/``bytes`` copies of the
   value that this class cannot pin or wipe. An attacker who can read your process memory
@@ -107,37 +110,52 @@ class _ProtectedStr(str):
         return str.__new__(cls, value)
 
     def __str__(self) -> str:
+        # Under enforcement, str()/print()/'%s' raise instead of masking — a loud failure so an
+        # accidental (or deliberate) str-dump is caught. With enforcement off, it masks as before.
+        # Honest limit: the *base* str.__str__(self) call skips this method entirely and returns
+        # the real value — the str type is immutable, so that path cannot be intercepted.
+        if _enforce:
+            _raise_extraction("str")
         return "[ranbval:secret]"
 
     def __repr__(self) -> str:
+        # repr stays masked even under enforcement: error reporters (Sentry) and debuggers repr()
+        # locals, and raising there would break error reporting itself.
         return "SecretString(***)"
 
     def __format__(self, spec: str) -> str:
-        # Python's str.__format__ calls str(self) internally, hitting __str__ and
-        # returning "[ranbval:secret]" — which breaks SDK f-string header construction.
-        # self[:] slices the underlying str buffer, returning a plain str with the
-        # real value without going through __str__. format() on that plain str works
-        # correctly, so f"Bearer {key}" in SDK code builds the right Authorization header.
-        # print(x) (which calls __str__ directly) remains masked.
-        return format(self[:], spec)
+        # Python's str.__format__ calls str(self) internally, hitting __str__ and returning
+        # "[ranbval:secret]" — which breaks SDK f-string header construction. We reconstruct the
+        # real value via the *base* str.__getitem__ (NOT self[:], which now hits our blocking
+        # __getitem__), so f"Bearer {key}" builds the right Authorization header while external
+        # slicing stays blocked. print(x) (which calls __str__ directly) remains masked.
+        return format(str.__getitem__(self, slice(None)), spec)
+
+    def __getitem__(self, key):
+        # Slicing / indexing a revealed value (``val[:]``, ``val[0]``, ``val[1:5]``) reads the
+        # plaintext out character by character — an extraction path. Reported, and (under
+        # enforcement, the default) BLOCKED. The SDK's own f-string path uses the base
+        # str.__getitem__ (see __format__), so legitimate header building is unaffected.
+        # Honest limit: ``str.__getitem__(val, ...)`` on the base class still bypasses this.
+        _guard_reveal("slice")
+        return str.__getitem__(self, key)
 
     def __iter__(self):
         # Character-by-character iteration is the signature of an in-memory extraction
         # (``''.join(ch for ch in key.use())``, ``list(key.use())``, a comprehension) — a
-        # legitimate SDK never iterates an API key. We do NOT block it (that would be
-        # futile and breaks nothing legitimate); we REPORT it to the opt-in access monitor
-        # and still yield the real characters, so honest use is unaffected but theft leaves
-        # a trace. f-strings hit __format__ (which slices, not iterates), so no false alarm.
-        _notify_reveal("iteration")
+        # legitimate SDK never iterates an API key. Reported to the access monitor, and (in
+        # enforcement mode, the default) BLOCKED with RanbvalSecurityError so the theft fails
+        # loudly. f-strings hit __format__ (which slices, not iterates), so no false alarm.
+        _guard_reveal("iteration")
         return super().__iter__()
 
     def encode(self, encoding: str = "utf-8", errors: str = "strict") -> bytes:
         # ``val.encode()`` turns the secret into raw bytes — an extraction path (and how
-        # ``bcrypt.hashpw`` etc. take it). Report it, then return the real bytes. Note: some
-        # signing SDKs (AWS SigV4/HMAC) and DB drivers encode the credential legitimately, so
-        # this signal can be a false positive; it never blocks. (OpenAI-style header building
-        # hits __format__ on a plain str, not this method, so it stays quiet.)
-        _notify_reveal("encode")
+        # ``bcrypt.hashpw`` etc. take it). Reported, and (in enforcement mode, the default)
+        # BLOCKED. Note: some signing SDKs (AWS SigV4/HMAC) and DB drivers encode the credential
+        # legitimately — if one trips this, call set_enforcement(False). (OpenAI-style header
+        # building hits __format__ on a plain str, not this method, so it stays quiet.)
+        _guard_reveal("encode")
         return super().encode(encoding, errors)
 
     # Serialization is a real accidental-leak path: error reporters (Sentry) pickle locals,
@@ -177,6 +195,94 @@ def _notify_reveal(method: str) -> None:
             pass
 
 
+# ── Enforcement (strict by default) ───────────────────────────────────────────
+# When enforcement is on, a detected extraction (iteration / encode / slice / buffer read) is
+# not merely reported — it raises ``RanbvalSecurityError`` so the offending code fails loudly
+# instead of silently walking off with the plaintext. Honest limit: this stops the *naive*
+# vectors; the base ``str`` methods (``str.__str__(val)``, ``str.__getitem__(val, ...)``) and the
+# real slot ``object.__getattribute__(s, "_b")`` still bypass it in-process and cannot be blocked.
+# Only ``[proxy]`` secrets are absolute. Turn off with ``set_enforcement(False)``.
+_enforce: bool = True
+
+_EXTRACTION_MESSAGE = {
+    "iteration": (
+        "Ranbval: character-by-character iteration of a secret is blocked — this is how "
+        "in-memory extraction (''.join(c for c in key.use())) works. Pass the value straight "
+        "to your SDK/HTTP client instead. If a legitimate library needs to iterate it, call "
+        "set_enforcement(False); for absolute safety use a [proxy] secret."
+    ),
+    "encode": (
+        "Ranbval: encoding a secret to bytes is blocked (an extraction path). Pass key.use() "
+        "directly to the client that needs it. If a legitimate signer/driver must encode it "
+        "(e.g. AWS SigV4, a DB driver), call set_enforcement(False); a [proxy] secret avoids "
+        "the plaintext entirely."
+    ),
+    "slice": (
+        "Ranbval: slicing/indexing a secret (val[:], val[0]) is blocked — it reads the plaintext "
+        "out character by character. Pass key.use() straight to your client; f-strings still work. "
+        "(set_enforcement(False) to disable; a [proxy] secret is the only absolute guarantee.)"
+    ),
+    "str": (
+        "Ranbval: str()/print()/'%s' of a secret is blocked under enforcement (it is masked when "
+        "enforcement is off). Pass key.use() straight to your client; f-strings build headers fine. "
+        "Note: the base str.__str__(val) call CANNOT be intercepted (the str type is immutable) — "
+        "only a [proxy] secret keeps the value off the client entirely. (set_enforcement(False) to disable.)"
+    ),
+    "buffer_read": (
+        "Ranbval: reading a secret's internal buffer (_buf/_pad) is blocked — no legitimate "
+        "caller touches these. Use key.use() at the point of use. (set_enforcement(False) to "
+        "disable; a [proxy] secret is the only absolute guarantee.)"
+    ),
+}
+
+
+def set_enforcement(enabled: bool) -> None:
+    """Turn extraction enforcement on/off process-wide (default: on).
+
+    On  → a detected extraction (iteration / encode / raw buffer read) raises
+          :class:`RanbvalSecurityError`.
+    Off → the extraction is only reported to the access monitor (detect + notify), and the
+          real value is returned — legacy behaviour, for when a legitimate library trips it.
+    """
+    global _enforce
+    _enforce = bool(enabled)
+
+
+def is_enforced() -> bool:
+    """True when extraction attempts raise (strict mode). See :func:`set_enforcement`."""
+    return _enforce
+
+
+def _guard_reveal(method: str) -> None:
+    """Report the reveal-side signal, then (in enforcement mode) raise to stop the extraction.
+
+    The notify runs first so the Live Monitor still records the attempt before the caller
+    crashes; the raise is what converts silent theft into a loud, alerting failure.
+    """
+    _notify_reveal(method)
+    if _enforce:
+        _raise_extraction(method)
+
+
+def _raise_extraction(method: str) -> None:
+    """Raise the extraction error (no notify). Used by paths — like ``str()`` — that are masked
+    (and frequent) when enforcement is off, so we must not flood the monitor with events."""
+    from ranbval_sdk.exceptions import RanbvalSecurityError
+
+    raise RanbvalSecurityError(
+        _EXTRACTION_MESSAGE.get(method, f"Ranbval: blocked secret extraction via {method}."),
+        code="secret_extraction_blocked",
+        method=method,
+    )
+
+
+def _reconstruct(buf: bytearray, pad: bytearray) -> bytes:
+    """XOR-unmask the stored buffer back to plaintext bytes. Module-level (not a method) so a
+    caller cannot reveal a secret via ``s.<method>()`` — the SDK reads the slots with
+    ``object.__getattribute__`` and calls this internally."""
+    return bytes(b ^ p for b, p in zip(buf, pad, strict=True))
+
+
 # Set by :mod:`ranbval_sdk.config.reveal`. Called with the secret's label inside ``.use()``;
 # it raises if that secret is restricted to a reveal scope and we are not inside one.
 _reveal_gate: object = None
@@ -243,14 +349,20 @@ def install_output_guards() -> None:
 class SecretString:
     """Holds a decrypted secret in memory, XOR-masked with a per-instance random pad.
 
-    The plaintext is never stored as-is: ``_buf`` holds ``plaintext XOR _pad``, so reading the
-    internal buffer directly (``object.__getattribute__(s, "_buf")``) yields only garbage. To
-    reconstruct the value you must read *both* slots and know the scheme — which pushes any
-    reader back through :meth:`use` (the gated, audited access point). This is bar-raising, not
-    absolute (a determined insider can read both slots); it closes the naive one-slot bypass.
+    The plaintext is never stored as-is: the real bytes live in the private slots ``_b`` (=
+    ``plaintext XOR _p``) and ``_p`` (the pad), so even reading one slot yields only garbage.
+
+    ``_buf`` and ``_pad`` are **honeypot properties**: any read of them — including the
+    ``object.__getattribute__(s, "_buf")`` form that used to bypass the class — fires the
+    reveal guard and (under enforcement) raises. This closes the known buffer-read PoC.
+
+    **Honest limit.** The real slots ``_b`` / ``_p`` still exist and can be read with
+    ``object.__getattribute__(s, "_b")`` by anyone who reads this (open-source) file — it is
+    bar-raising against naive/automated extraction, not an absolute guarantee. The only value
+    that never exists in the client process is a ``[proxy]`` secret.
     """
 
-    __slots__ = ("_buf", "_pad", "_label", "_wiped")
+    __slots__ = ("_b", "_p", "_label", "_wiped")
 
     def __init_subclass__(cls, **kwargs: object) -> None:
         raise TypeError("SecretString cannot be subclassed")
@@ -261,22 +373,32 @@ class SecretString:
         buf = bytearray(b ^ p for b, p in zip(raw, pad, strict=True))  # plaintext XOR pad
         _try_mlock(buf)  # pin to RAM — no swap to disk
         _try_mlock(pad)
-        object.__setattr__(self, "_buf", buf)
-        object.__setattr__(self, "_pad", pad)
+        object.__setattr__(self, "_b", buf)
+        object.__setattr__(self, "_p", pad)
         object.__setattr__(self, "_label", label)
         object.__setattr__(self, "_wiped", False)
 
-    def _plaintext_bytes(self) -> bytes:
-        """Reconstruct the plaintext bytes from the masked buffer (transient — for use/eq/hash)."""
-        buf = object.__getattribute__(self, "_buf")
-        pad = object.__getattribute__(self, "_pad")
-        return bytes(b ^ p for b, p in zip(buf, pad, strict=True))
+    # ── Buffer honeypots ───────────────────────────────────────────────────
+    # Reading ``s._buf`` / ``s._pad`` is a reveal-gate / monitor bypass — a normal caller never
+    # touches these. Exposing them as *properties* (data descriptors) means the guard fires even
+    # for ``object.__getattribute__(s, "_buf")``, which the old __slots__ layout let through.
+    # The SDK's own internals read the real slots ``_b`` / ``_p`` directly, so they don't trip it.
+
+    @property
+    def _buf(self) -> bytearray:
+        _guard_reveal("buffer_read")
+        return object.__getattribute__(self, "_b")
+
+    @property
+    def _pad(self) -> bytearray:
+        _guard_reveal("buffer_read")
+        return object.__getattribute__(self, "_p")
 
     # ── Memory wipe ────────────────────────────────────────────────────────
 
     def wipe(self) -> None:
         """Zero the secret bytes in memory and unpin from RAM. After this, use() raises RuntimeError."""
-        for name in ("_buf", "_pad"):
+        for name in ("_b", "_p"):
             b = object.__getattribute__(self, name)
             _try_munlock(b)  # unpin before zeroing
             b[:] = b"\x00" * len(b)
@@ -293,6 +415,9 @@ class SecretString:
     # ── All display paths are blocked ──────────────────────────────────────
 
     def __str__(self) -> str:
+        # Under enforcement, str()/print() of the sealed wrapper raises (loud); otherwise masks.
+        if _enforce:
+            _raise_extraction("str")
         return "[ranbval:secret]"
 
     def __repr__(self) -> str:
@@ -310,12 +435,27 @@ class SecretString:
                 other, "_wiped"
             ):
                 return False
-            # Deobfuscate both (each has its own pad) and compare in constant time.
-            return hmac.compare_digest(self._plaintext_bytes(), other._plaintext_bytes())
+            # Deobfuscate both (each has its own pad) and compare in constant time. Read the
+            # slots via object.__getattribute__ so we don't trip our own buffer-read monitor.
+            return hmac.compare_digest(
+                _reconstruct(
+                    object.__getattribute__(self, "_b"),
+                    object.__getattribute__(self, "_p"),
+                ),
+                _reconstruct(
+                    object.__getattribute__(other, "_b"),
+                    object.__getattribute__(other, "_p"),
+                ),
+            )
         return NotImplemented
 
     def __hash__(self) -> int:
-        return hash(self._plaintext_bytes())
+        return hash(
+            _reconstruct(
+                object.__getattribute__(self, "_b"),
+                object.__getattribute__(self, "_p"),
+            )
+        )
 
     # Block attribute setting from outside
     def __setattr__(self, _name: str, _value: object) -> None:
@@ -367,7 +507,11 @@ class SecretString:
         from ranbval_sdk.crypto.audit import record_access
 
         record_access(label)
-        return _ProtectedStr(self._plaintext_bytes().decode("utf-8"))
+        plaintext = _reconstruct(
+            object.__getattribute__(self, "_b"),
+            object.__getattribute__(self, "_p"),
+        )
+        return _ProtectedStr(plaintext.decode("utf-8"))
 
     def __del__(self) -> None:
         try:
@@ -378,7 +522,7 @@ class SecretString:
 
     def __len__(self) -> int:
         """Length of the secret in bytes (safe — does not reveal content)."""
-        return len(object.__getattribute__(self, "_buf"))
+        return len(object.__getattribute__(self, "_b"))
 
     @property
     def label(self) -> str:

{ranbval_sdk-2.2.0 → ranbval_sdk-2.3.0}/src/ranbval_sdk/exceptions.py

@@ -98,6 +98,21 @@ class ProxyError(RanbvalError, RuntimeError):
     default_code = "proxy_error"
 
 
+class RanbvalSecurityError(RanbvalError, PermissionError):
+    """A revealed secret was manipulated in a way that signals in-memory extraction
+    (char-by-char iteration, ``.encode()`` to bytes, or a direct read of the internal
+    buffer) while enforcement is on. Raised to turn silent theft into a loud failure.
+
+    This is a **naive-attacker deterrent, not a guarantee** — once ``.use()`` returns a real
+    ``str``, the base ``str`` methods (``str.__str__(val)``, ``str.__getitem__(val, ...)``) and
+    the real buffer slot (``object.__getattribute__(s, "_b")``) still reach the plaintext
+    in-process and cannot be blocked. Only ``[proxy]`` secrets (plaintext never enters the client)
+    are absolute. Disable with ``set_enforcement(False)`` if a legitimate library trips it.
+    """
+
+    default_code = "secret_extraction_blocked"
+
+
 __all__ = [
     "RanbvalError",
     "RanbvalDecryptError",
@@ -106,4 +121,5 @@ __all__ = [
     "RepoNotAllowedError",
     "RepoPolicyError",
     "ProxyError",
+    "RanbvalSecurityError",
 ]