diff --git a/README.md b/README.md index dbe626f..8189756 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,14 @@ response = await vault.invoke_llm(token, { "max_tokens": 200, "messages": [{"role": "user", "content": "..."}], }) + +# Signing scopes: HMAC-SHA256 with the credential the scope resolves to. The +# agent gets a hex signature, the key stays in Rust. No method returns a secret. +vault.register_scope_secret("sign.", "hmac_key") # a secret loaded like the API key +sign_token = vault.issue_token( + scope="sign.invoices", context="billing", max_uses=1, bootstrap_token=bootstrap, +) +signature = vault.sign(sign_token, b"invoice #1001 :: 4200.00 CHF") ``` For the strongest containment, run the out-of-process **broker**. The key lives in a separate process and the agent holds only token IDs. `cage.broker.spawn_broker` starts it, and `cage.adapters.CagedAnthropic` / `CagedOpenAI` take the provider SDKs' call shape (they return the provider's JSON as a dict). The broker needs an issuance policy, so set `CAGE_ISSUANCE_SCOPES` (for example `llm.,sign.`) before you start it. See [`examples/broker_demo.py`](./examples/broker_demo.py), which drives a real agent child process that is refused every escalation, and [`examples/agent_broker_adapter.py`](./examples/agent_broker_adapter.py). Read [DEPLOY.md](./DEPLOY.md) before running the broker in production: it only keeps the key from a same-user agent when the agent cannot control how the broker starts. @@ -108,7 +116,6 @@ These are the gaps as of v0.1. Reports and fixes are welcome (see [SECURITY.md]( - The provider pin binds a secret's name, and secrets are unpinned by default. - The CA allowlist filters on the root CA only, by organization name. Subordinate CAs run by other organizations under an admitted root are accepted, and revocation is not checked. - In-process, `register_scope_secret` and the audit writer need no authority. In-process code is trusted. The broker exposes neither. -- `vault.consume()` still exists for scopes without a Rust transport. It is deprecated, refused by default, and will be removed before 1.0. ## Verifying signed releases diff --git a/crates/cage-core/src/gate.rs b/crates/cage-core/src/gate.rs index d4a2d07..7870f8c 100644 --- a/crates/cage-core/src/gate.rs +++ b/crates/cage-core/src/gate.rs @@ -297,12 +297,6 @@ pub struct Gate { /// When true, token issuance/revocation do NOT require the bootstrap token. /// Development/testing ONLY — production stays fail-closed (the default). insecure_dev_mode: bool, - /// When true, [`Gate::consume`] may hand plaintext back to the caller. - /// Development ONLY — and deliberately **separate** from `insecure_dev_mode`: - /// the switch that re-enables the deprecated leak must not be the same switch - /// that waives control-plane auth, or restoring `consume()` would silently - /// unlock issuance/revocation too. - allow_plaintext_consume: bool, /// Monotonic issue stamp per token — the TTL is enforced against this, not the /// wallclock, so a host clock rollback cannot revive or extend a token. token_issued_at: HashMap, @@ -337,7 +331,6 @@ impl Gate { policy_fingerprint: None, issued_per_entry: HashMap::new(), insecure_dev_mode: false, - allow_plaintext_consume: false, token_issued_at: HashMap::new(), operator_keys: Vec::new(), cp_nonces: HashMap::new(), @@ -398,20 +391,6 @@ impl Gate { } } - /// Enable the deprecated plaintext [`Gate::consume`] path. Development ONLY; - /// same construction-only contract and chain entry as - /// [`Gate::set_insecure_dev_mode`]. - /// - /// It is a switch of its own rather than a facet of `insecure_dev_mode` on - /// purpose: an integrator who needs the leak for a scope with no gated - /// operation yet must not have to waive control-plane auth to get it. - pub fn set_allow_plaintext_consume(&mut self, enabled: bool) { - self.allow_plaintext_consume = enabled; - if enabled { - self.audit("vault", "plaintext_consume_enabled", &serde_json::json!({})); - } - } - /// Store a credential in the vault (control plane / broker startup). The /// vault is never exposed directly — callers reach it only through the gated /// operations on this authority, so a credential cannot be read back out. @@ -929,49 +908,6 @@ impl Gate { ); } - /// Token-gated plaintext retrieval — the deprecated `consume` path. Authorizes - /// against `requested_scope`, charges a use, audits, and returns the secret as a - /// String. The plaintext crosses the binding boundary here; this is the - /// deprecated leak path, kept **token-gated** until per-provider transports - /// replace it (so it is never an *un*gated bypass like the old raw retrieve). - /// - /// **Off unless [`Gate::set_allow_plaintext_consume`] was set.** Because it - /// hands plaintext back into the caller's address space, a gate refuses it - /// structurally by default — so the "no plaintext key in the agent" property - /// holds for a gate built at the defaults, regardless of the deprecation. The - /// switch is same-trust-domain hygiene, not a boundary: a caller who controls - /// construction can build a gate with it on. The token is authorized first, - /// so the refusal — audited like every other — is keyed on a validated token - /// and a forged one is rejected as unknown, exactly as on the other ops. Full - /// removal follows once every provider a customer needs has a Rust transport. - pub fn consume(&mut self, token_id: &str, requested_scope: &str) -> Result { - self.authorize(token_id, Some(requested_scope), None)?; - if !self.allow_plaintext_consume { - self.audit( - token_id, - "consume_refused_plaintext_disabled", - &serde_json::json!({ "scope": requested_scope }), - ); - return Err(CageError::Refused( - "consume() returns plaintext into the caller's address space and is \ - disabled by default. Use a gated op that keeps the key in the \ - vault — invoke for LLM scopes, sign for signing scopes; a scope \ - with neither is not production-supported." - .to_string(), - )); - } - let secret = self.resolve_secret_for(token_id, requested_scope)?; - let uses = self.record_use(token_id)?; - let value = self.vault.retrieve_secret(&secret)?; - // Fail-closed: the plaintext is returned only once its audit entry exists. - self.audit_checked( - token_id, - "consumed", - &serde_json::json!({"scope": requested_scope, "use_count": uses}), - )?; - Ok(value) - } - /// Configure the release-signing policy (control plane). The requester never /// supplies the policy — a compromised CI must not be able to relax it. pub fn set_release_policy(&mut self, policy: ReleasePolicy) { @@ -1311,7 +1247,7 @@ impl Gate { /// Fail-closed audit: like [`audit`](Self::audit) but propagates an append /// failure instead of swallowing it. Used on the secret-materializing success - /// paths (`sign` / `invoke` / `consume` / `sign_release`) so a secret-derived + /// paths (`sign` / `invoke` / `sign_release`) so a secret-derived /// result is never returned to the caller without its audit-chain entry — the /// append is part of the operation, not best-effort. In practice `append_audit` /// only fails on malformed JSON, which the gate never constructs, so this never @@ -1553,96 +1489,9 @@ mod tests { } #[test] - fn consume_is_token_gated_and_use_counted() { - let mut g = gate_with_secret(); - g.set_allow_plaintext_consume(true); - let t = g.issue_token("sign.x", "c", None, Some(1), None).unwrap(); - assert_eq!( - g.consume(&t.token_id, "sign.x").unwrap(), - "super-secret-value" - ); - // Over max_uses → refused (no second plaintext). - assert!(matches!( - g.consume(&t.token_id, "sign.x").unwrap_err(), - CageError::Refused(_) - )); - } - - #[test] - fn consume_refused_unless_plaintext_is_explicitly_allowed() { - // A sealed, default-built gate (no dev mode, no leak switch) refuses - // consume() on a legitimately issued token — the plaintext-into-the-caller - // path is opt-in only. - let mut g = sealed_gate_with_secret(); - let bootstrap = g.unseal().unwrap(); - let t = g - .issue_token( - "sign.x", - "c", - None, - Some(1), - Some(ControlAuth::Bootstrap(&bootstrap)), - ) - .unwrap(); - assert!(matches!( - g.consume(&t.token_id, "sign.x").unwrap_err(), - CageError::Refused(_) - )); - assert!(g - .audit_log_snapshot() - .iter() - .any(|e| e.event == "consume_refused_plaintext_disabled" && e.entity_id == t.token_id)); - } - - #[test] - fn consume_on_a_forged_token_is_rejected_as_unknown_even_when_disabled() { - // authorize() runs before the switch check, so a forged probe is recorded - // the way every other op records it — not as a plaintext refusal keyed on - // an attacker-chosen id. - let mut g = sealed_gate_with_secret(); - assert!(matches!( - g.consume(&"00".repeat(16), "sign.x").unwrap_err(), - CageError::Refused(_) - )); - let log = g.audit_log_snapshot(); - assert!(log.iter().any(|e| e.event == "rejected_unknown_token")); - assert!(!log - .iter() - .any(|e| e.event == "consume_refused_plaintext_disabled")); - } - - #[test] - fn insecure_dev_mode_alone_does_not_re_enable_consume() { - // The two switches are decoupled: waiving control-plane auth must not also - // restore the plaintext path, or the escape hatch for one becomes the - // detonator for the other. `gate_with_secret()` is already in dev mode. - let mut g = gate_with_secret(); - assert!(g.verify_control_auth("issue", b"", None), "dev mode is on"); - let t = g.issue_token("sign.x", "c", None, Some(1), None).unwrap(); - assert!(matches!( - g.consume(&t.token_id, "sign.x").unwrap_err(), - CageError::Refused(_) - )); - } - - #[test] - fn plaintext_consume_alone_does_not_waive_control_auth() { - // The inverse direction of the decoupling: opting into the leak must not - // also waive control-plane auth. - let mut g = sealed_gate_with_secret(); - g.set_allow_plaintext_consume(true); - assert!(!g.verify_control_auth("issue", b"", None)); - assert!(matches!( - g.issue_token("sign.x", "c", None, Some(1), None) - .unwrap_err(), - CageError::Refused(_) - )); - } - - #[test] - fn enabling_a_dev_switch_is_recorded_on_the_chain() { - // A default gate's chain carries neither entry; enabling a waiver writes one - // before anything can be issued or consumed under it. + fn enabling_the_dev_switch_is_recorded_on_the_chain() { + // A default gate's chain carries no such entry. Enabling the waiver writes + // one before anything can be issued under it. let g = Gate::new(); let ev = |g: &Gate, name: &str| { g.audit_log_snapshot() @@ -1651,37 +1500,11 @@ mod tests { .count() }; assert_eq!(ev(&g, "insecure_dev_mode_enabled"), 0); - assert_eq!(ev(&g, "plaintext_consume_enabled"), 0); let mut g = Gate::new(); g.set_insecure_dev_mode(false); - g.set_allow_plaintext_consume(false); - assert_eq!(g.audit_log_len(), 0, "the default-false calls stay silent"); + assert_eq!(g.audit_log_len(), 0, "the default-false call stays silent"); g.set_insecure_dev_mode(true); - g.set_allow_plaintext_consume(true); assert_eq!(ev(&g, "insecure_dev_mode_enabled"), 1); - assert_eq!(ev(&g, "plaintext_consume_enabled"), 1); - assert!(g.verify_audit_chain()); - } - - #[test] - fn consume_refusal_is_audited() { - // A refused consume() must leave a chain entry like every other refusal in - // the gate — otherwise a compromised agent could probe the raw-key path in - // production with zero trace (invariant 4). - let mut g = gate_with_secret(); - let t = g.issue_token("sign.x", "c", None, Some(1), None).unwrap(); - assert!(matches!( - g.consume(&t.token_id, "sign.x").unwrap_err(), - CageError::Refused(_) - )); - let log = g.audit_log_snapshot(); - let refusals: Vec<_> = log - .iter() - .filter(|e| e.event == "consume_refused_plaintext_disabled") - .collect(); - assert_eq!(refusals.len(), 1); - assert_eq!(refusals[0].entity_id, t.token_id); - assert!(refusals[0].data_json.contains("\"scope\":\"sign.x\"")); assert!(g.verify_audit_chain()); } diff --git a/crates/cage-core/src/vault.rs b/crates/cage-core/src/vault.rs index 604eb1b..8ec50f4 100644 --- a/crates/cage-core/src/vault.rs +++ b/crates/cage-core/src/vault.rs @@ -370,23 +370,6 @@ impl Vault { self.encrypt_and_store(name, plaintext_bytes.as_slice()) } - /// Decrypt and return the stored secret as a `String` (deprecated path — - /// prefer `invoke`, which never materializes plaintext outside the vault). - pub fn retrieve_secret(&self, name: &str) -> Result { - let plaintext_bytes = self.decrypt_to_zeroizing(name)?; - match String::from_utf8(plaintext_bytes.to_vec()) { - Ok(s) => Ok(s), - Err(e) => { - // The FromUtf8Error owns the (non-Zeroizing) plaintext Vec — wipe it - // before it is freed, otherwise a binary or corrupt-but-authenticating - // secret leaks 100% of the time on this error path. - let mut leaked = e.into_bytes(); - leaked.zeroize(); - Err(CageError::Crypto("secret is not valid UTF-8".into())) - } - } - } - /// True if a secret with this name is stored. pub fn has_secret(&self, name: &str) -> bool { self.store.contains_key(name) diff --git a/python/cage/core/gate.py b/python/cage/core/gate.py index f2522c9..7dffb7b 100644 --- a/python/cage/core/gate.py +++ b/python/cage/core/gate.py @@ -150,7 +150,7 @@ def register_scope_secret(self, scope_prefix: str, secret_name: str) -> None: to the secret stored under "llm_api_key". """ if self._has_rust_authority: - # Resolution happens in Rust (invoke/consume/sign), so the registry + # Resolution happens in Rust (invoke/sign), so the registry # must live there. self._secure_backend.register_scope_secret(scope_prefix, secret_name) return diff --git a/python/cage/token.py b/python/cage/token.py index 475ae49..f053a74 100644 --- a/python/cage/token.py +++ b/python/cage/token.py @@ -38,7 +38,7 @@ class CapabilityToken: issued_at : UTC timestamp at issue time ttl_seconds : hard expiry max_uses : cumulative use ceiling (Invariant 3) - use_count : incremented on each consume()/invoke_llm(); never decremented + use_count : incremented on each sign()/invoke_llm(); never decremented revoked : True if vault.revoke() was called on this token ``scope`` and ``context`` are required; the rest carry defaults. (Dataclass diff --git a/python/cage/vault.py b/python/cage/vault.py index 8a1cb0a..4fcda18 100644 --- a/python/cage/vault.py +++ b/python/cage/vault.py @@ -10,10 +10,10 @@ Python — ChaCha20 (no AEAD, no real zeroize) — development fallback All token lifecycle, revocation, and audit logic is delegated to the Gate — -those operations handle no secret bytes. The ONLY path to a secret value is -through ``consume()`` (deprecated) or ``invoke_llm()`` (preferred); both -authorize against the Gate, record a use, append to the audit chain, and — for -``invoke_llm()`` — keep the decrypted key inside Rust (never crossing PyO3). +those operations handle no secret bytes. No ``SecretVault`` method returns a +stored secret. The only uses of one are ``invoke_llm()`` and ``sign()``, and both authorize against +the Gate, record a use, append to the audit chain, and keep the decrypted key +inside Rust (never crossing PyO3). """ from __future__ import annotations @@ -45,18 +45,6 @@ def _require_bool(name: str, value: object) -> bool: return value -def _warn_plaintext_consume() -> None: - # Emitted only when plaintext is actually about to be handed back — a refused - # consume() must surface as CageViolation, never as this warning. - warnings.warn( - "vault.consume() returns a Python str — bytes cross PyO3 and " - "persist in CPython's interned-string heap. Prefer " - "vault.invoke_llm() for the Anthropic path. Per-provider Rust " - "transports replace consume() incrementally.", - DeprecationWarning, - stacklevel=3, - ) - logger = logging.getLogger("cage.vault") # --------------------------------------------------------------------------- @@ -214,9 +202,9 @@ class SecretVault: Rust — ChaCha20Poly1305 AEAD + zeroize-on-drop + mlock + rustls transport Python — ChaCha20 (no AEAD, no real zeroize) — development fallback - The ONLY path to a secret value is consume() (deprecated) or invoke_llm() - (preferred), which authorize via the Gate, record a use, append to the audit - chain, and — for invoke_llm() — keep the decrypted key inside Rust. + No method of this class returns a stored secret. The only uses of one are + invoke_llm() and sign(), which authorize via the Gate, record a use, append + to the audit chain, and keep the decrypted key inside Rust. """ def __init__( @@ -227,7 +215,6 @@ def __init__( insecure_dev_mode: bool = False, strict_backend: bool = False, broker_only_issuance: bool = False, - allow_plaintext_consume: bool = False, ) -> None: """ Parameters @@ -264,13 +251,6 @@ def __init__( authority out of the application process entirely, rather than relying on an in-process bootstrap. Token-gated *use* (``invoke_llm``) is unaffected — only issuance/revocation move to the broker. - allow_plaintext_consume : bool - If True, re-enables the deprecated ``consume()`` path, which returns - the secret as a Python ``str``. Development ONLY; the default is False - and a vault left at the default refuses ``consume()`` structurally. - This is a switch of its own — **not** a facet of ``insecure_dev_mode`` - — so a caller who still needs the leak for a scope with no non-leaking - operation does not have to waive control-plane auth to get it. """ # Broker-only issuance: disables the in-process control plane so the # operator authority never lives in the application process. Opt in via the @@ -280,19 +260,12 @@ def __init__( in ("1", "true", "yes", "on") ) - # Both loosening switches are typed strictly, never coerced — see - # _require_bool. consume() is refused by default; on the Rust backend the - # core enforces that, and this flag is consulted only on the pure-Python - # fallback, where it is the sole enforcement point. + # The loosening switch is typed strictly, never coerced (see _require_bool). insecure_dev_mode = _require_bool("insecure_dev_mode", insecure_dev_mode) - self._allow_plaintext_consume = _require_bool( - "allow_plaintext_consume", allow_plaintext_consume - ) if _RUST_BACKEND_AVAILABLE: self._backend: _PythonVaultBackend | _RustBackend = _RustBackend( # type: ignore[valid-type] insecure_dev_mode=insecure_dev_mode, - allow_plaintext_consume=allow_plaintext_consume, ) self._backend_name = "rust" else: @@ -635,78 +608,48 @@ def revoke(self, token_id: str, bootstrap_token: Optional[object] = None) -> boo # Secret access — token-gated # ------------------------------------------------------------------ - def consume(self, token: CapabilityToken, scope: str) -> str: + def sign(self, token: CapabilityToken, payload: bytes | str) -> str: """ - DEPRECATED and **dev-only** — use `invoke_llm()` instead for LLM - provider calls. - - Returns the cleartext secret as a Python `str`, which means the - bytes cross the Rust/Python boundary and persist in CPython's - interned-string heap. This is the plaintext-str leak that the - CAGE design forbids on critical paths, so it is **refused by - default** — it runs only when the vault was constructed with - ``allow_plaintext_consume=True``. - - Kept available (behind that opt-in) for non-LLM scopes and for - non-Anthropic providers until per-provider Rust transport adapters land; - in production such scopes have no ``consume`` path and are unsupported - until a non-leaking operation exists for them. Callers MUST pass the - return value inline and MUST NOT assign to a variable. + Token-gated HMAC-SHA256 over ``payload`` with the credential the token's + scope resolves to. Returns the hex signature. The key never leaves Rust. + + The token's scope must be in the ``sign`` namespace (``sign.``), + and that namespace must be registered to a stored secret with + ``register_scope_secret``. Authorize, charge and sign are one operation in + the Rust gate, audited as ``signed``. A ``str`` payload is signed as its + UTF-8 bytes. + + Holds only on the Rust backend. The pure-Python fallback would have to + read the key into a Python ``str`` to sign, so it refuses, as + ``invoke_llm`` does. """ - if self._backend_name == "rust": - # The core is the enforcement point: it authorizes, then refuses (and - # audits) unless the gate was constructed with - # allow_plaintext_consume=True; when it is on, authorize + charge + - # audit + retrieve are one operation co-located with the secret. The - # plaintext str still crosses PyO3 (the deprecated leak), but it is - # never reachable as an *un*gated bypass. - try: - value = self._backend.consume(token.token_id, scope) - except ValueError as exc: - _raise_mapped(exc) - _warn_plaintext_consume() - return value - - # Python fallback (dev only). - # Structural refusal (Invariant 6): authorize against the gate's own - # record, never the caller-supplied object's fields. - canonical = self._gate.authorize(token, scope) - - if not self._allow_plaintext_consume: - # The only enforcement point on the fallback (its backend store is - # ungated by design). Audited like every other refusal, tagged with the - # writing layer because it arrives through the generic append channel. + if self._backend_name != "rust": + # Structural refusal first (Invariant 6), so a forged id is recorded as + # unknown by the gate. Then the refusal itself goes on the chain, keyed + # on the validated token, like every other refusal (Invariant 4). + canonical = self._gate.authorize(token) self._gate.append_audit( - canonical.token_id, - "consume_refused_plaintext_disabled", - {"scope": scope, "layer": "facade"}, + canonical.token_id, "sign_refused_no_rust_backend", {"layer": "facade"} ) raise CageViolation( - "vault.consume() is refused — it returns a Python str, leaking " - "plaintext into CPython's heap. Use invoke_llm() for LLM scopes " - "(the key never crosses PyO3) or the out-of-process broker " - "(BrokerClient.sign() for signing scopes; the cage.adapters " - "drop-ins for LLM calls); a scope with neither is not " - "production-supported yet." + "sign() requires the Rust backend, where the key stays inside the " + "gate. The pure-Python fallback would read it into a Python str, " + "so it refuses. Build the cage native extension " + "(maturin develop --release)." ) - - secret_key = self._gate.scope_to_secret(scope) - if not self._backend.has_secret(secret_key): - raise CageViolation( - f"No secret loaded for scope={scope!r} " - f"(expected stored name {secret_key!r})." + if isinstance(payload, str): + payload = payload.encode("utf-8") + elif not isinstance(payload, (bytes, bytearray, memoryview)): + # bytes(5) would sign five zero bytes. Refuse anything that is not + # a byte sequence or text. + raise TypeError( + f"payload must be bytes or str, got {type(payload).__name__}" ) - - # Increment cumulative use counter — Invariant 3 - canonical = self._gate.record_use(canonical) - - self._gate.append_audit( - canonical.token_id, "consumed", - {"scope": scope, "use_count": canonical.use_count}, - ) - - _warn_plaintext_consume() - return self._backend.retrieve_secret(secret_key) + try: + signature = self._backend.sign(token.token_id, bytes(payload)) + except ValueError as exc: + _raise_mapped(exc) + return signature async def invoke_llm( self, @@ -715,7 +658,7 @@ async def invoke_llm( provider: str = "anthropic", ) -> dict[str, Any]: """ - Token-gated LLM invocation — replaces `consume()` for LLM provider calls. + Token-gated LLM invocation. Authorizes the token, increments use_count, appends an audit entry, then delegates to the provider's transport which performs the HTTPS @@ -747,10 +690,14 @@ async def invoke_llm( # decrypted key never crosses PyO3, which holds ONLY on the Rust backend. # The pure-Python fallback would inject the key as a Python str — the exact # north-star violation this method exists to prevent — so refuse rather than - # silently leak. The fallback is not a production backend: consume() is - # dev-only there too, behind allow_plaintext_consume, and its in-process + # silently leak. The fallback is not a production backend: its in-process # store is ungated by design (strict_backend=True refuses the fallback). if self._backend_name != "rust": + # Same shape as sign(): validate the token, record the refusal, refuse. + canonical = self._gate.authorize(token) + self._gate.append_audit( + canonical.token_id, "invoke_refused_no_rust_backend", {"layer": "facade"} + ) raise CageViolation( "invoke_llm() requires the Rust backend for its zero-plaintext " "guarantee (the decrypted key never crosses PyO3). The pure-Python " diff --git a/src/lib.rs b/src/lib.rs index 7e5f1fb..1a95b2c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -12,9 +12,9 @@ The Python-visible object is the **`Gate`**, not the bare vault: the credential store and the capability authority are the *same* Rust object, so the token check and the secret use are one atomic operation that no in-process Python code can step around. There is deliberately **no** un-gated `retrieve_secret` / raw -`invoke` on this surface — the only paths to a secret value are the token-gated -`invoke` (zero-plaintext, key never crosses PyO3) and the deprecated, still -token-gated `consume`. +`invoke` on this surface, and no operation returns a stored secret at all. The +only uses of a secret are the token-gated `invoke` and `sign`, and on both the +key never crosses PyO3. The `Gate` is held behind a `Mutex` so every method borrows the pyclass as `&self` (shared). `invoke` reserves a use + decrypts under the lock, **releases @@ -79,15 +79,12 @@ impl RustGate { #[pymethods] impl RustGate { /// Construct a gate. `insecure_dev_mode` waives the bootstrap requirement on - /// issuance/revocation; `allow_plaintext_consume` re-enables the deprecated - /// `consume()` leak. Both are development/tests ONLY, and both are constructor - /// arguments with no setter, so neither can be flipped from Python once the gate exists. - /// They are separate switches on purpose — see `Gate::set_allow_plaintext_consume`. + /// issuance/revocation. Development and tests ONLY. It is a constructor + /// argument with no setter, so it cannot be flipped from Python once the gate exists. #[new] - pub fn new(insecure_dev_mode: bool, allow_plaintext_consume: bool) -> Self { + pub fn new(insecure_dev_mode: bool) -> Self { let mut gate = Gate::new(); gate.set_insecure_dev_mode(insecure_dev_mode); - gate.set_allow_plaintext_consume(allow_plaintext_consume); RustGate(Mutex::new(gate)) } @@ -257,13 +254,6 @@ impl RustGate { } } - /// Deprecated token-gated plaintext retrieval. Token-gated (authorize + charge - /// + audit), but returns the secret as a Python `str` — the bytes cross PyO3 and - /// persist in CPython's interned-string heap. Removed before 1.0. - pub fn consume(&self, token_id: &str, scope: &str) -> PyResult { - self.lock().consume(token_id, scope).map_err(to_py) - } - /// HMAC-SHA256 sign with the vault-held key for the token's scope. The key /// never leaves the gate. pub fn sign(&self, token_id: &str, payload: &[u8]) -> PyResult { diff --git a/tests/test_authority_bypass_closed.py b/tests/test_authority_bypass_closed.py index 828584e..b340317 100644 --- a/tests/test_authority_bypass_closed.py +++ b/tests/test_authority_bypass_closed.py @@ -9,7 +9,6 @@ from __future__ import annotations import threading -import warnings import pytest @@ -25,9 +24,11 @@ def test_no_token_less_backend_bypass() -> None: pytest.skip("the un-gated bypass closure is Rust-backend specific") v.store_secret("llm_api_key", "sk-ant-SECRET") - # The ungated plaintext readers are gone from the native surface. + # The plaintext readers are gone from the native surface, the ungated ones + # and the token-gated consume() alike. assert not hasattr(v._backend, "retrieve_secret") assert not hasattr(v._backend, "decrypt_secret") + assert not hasattr(v._backend, "consume") # The only native invoke is token-gated: a fabricated token_id is refused # (structural refusal) before any network call or key decryption. @@ -74,24 +75,25 @@ def test_fail_closed_revoke_needs_bootstrap() -> None: assert v.revoke(token.token_id, bootstrap_token=bootstrap) is True -def test_concurrent_consume_does_not_double_spend() -> None: +def test_concurrent_sign_does_not_double_spend() -> None: """PoC3: concurrent use of a max_uses=1 token used to succeed N times because authorize and record_use straddled the await non-atomically. The Rust gate charges the use atomically, so a max_uses=1 token is spent exactly once even under concurrency.""" - v = SecretVault(insecure_dev_mode=True, allow_plaintext_consume=True) - v.store_secret("llm_api_key", "sk-secret-value") - token = v.issue_token(scope="llm.evaluate", context="race", max_uses=1) + v = SecretVault(insecure_dev_mode=True) + if v.backend != "rust": + pytest.skip("the atomic charge is enforced on the Rust authority") + v.store_secret("hmac_key", "k-secret-value") + v.register_scope_secret("sign.", "hmac_key") + token = v.issue_token(scope="sign.race", context="race", max_uses=1) results: list[str | None] = [] def worker() -> None: - with warnings.catch_warnings(): - warnings.simplefilter("ignore", DeprecationWarning) - try: - results.append(v.consume(token, "llm.evaluate")) - except CageViolation: - results.append(None) + try: + results.append(v.sign(token, b"payload")) + except CageViolation: + results.append(None) threads = [threading.Thread(target=worker) for _ in range(8)] for t in threads: @@ -99,21 +101,22 @@ def worker() -> None: for t in threads: t.join() - succeeded = [r for r in results if r == "sk-secret-value"] + succeeded = [r for r in results if r is not None] assert len(succeeded) == 1, ( f"max_uses=1 token was spent {len(succeeded)} times — double-spend" ) -def test_forged_token_cannot_drive_invoke_or_consume() -> None: +def test_forged_token_cannot_drive_sign() -> None: """Structural refusal on the shipped path: a fabricated CapabilityToken the vault never issued unlocks nothing, even though the type is constructable.""" - v = SecretVault(insecure_dev_mode=True, allow_plaintext_consume=True) - v.store_secret("llm_api_key", "sk-test") - forged = CapabilityToken(scope="llm.evaluate", context="attacker", max_uses=10) + v = SecretVault(insecure_dev_mode=True) + if v.backend != "rust": + pytest.skip("sign() is Rust-backend only") + v.store_secret("hmac_key", "k-test") + v.register_scope_secret("sign.", "hmac_key") + forged = CapabilityToken(scope="sign.x", context="attacker", max_uses=10) - with warnings.catch_warnings(): - warnings.simplefilter("ignore", DeprecationWarning) - with pytest.raises(CageViolation): - v.consume(forged, "llm.evaluate") + with pytest.raises(CageViolation): + v.sign(forged, b"payload") assert v.audit_chain_valid() diff --git a/tests/test_public_api.py b/tests/test_public_api.py index a3d358f..d419bbd 100644 --- a/tests/test_public_api.py +++ b/tests/test_public_api.py @@ -7,8 +7,6 @@ from __future__ import annotations -import warnings - import pytest @@ -49,7 +47,7 @@ def test_secretvault_public_methods_present() -> None: "store_secret", "load_from_env_file", "has_secret", "delete_secret", "configure", "register_scope_secret", "unseal", "is_unsealed", "issue_token", "revoke", - "consume", "invoke_llm", + "sign", "invoke_llm", "audit_chain_valid", "get_audit_log", "audit_head", "attestation_payload", "attestation_public_key", "record_attestation", ): @@ -61,14 +59,15 @@ def test_end_to_end_lifecycle_surface() -> None: """One pass through the canonical flow, asserting the shapes callers rely on.""" from cage import CapabilityToken, SecretVault - v = SecretVault(insecure_dev_mode=True, allow_plaintext_consume=True) - v.store_secret("llm_api_key", "sk-test") - tok = v.issue_token(scope="llm.evaluate", context="api-test", max_uses=2) + v = SecretVault(insecure_dev_mode=True) + if v.backend != "rust": + pytest.skip("sign() is Rust-backend only") + v.store_secret("hmac_key", "k-test") + v.register_scope_secret("sign.", "hmac_key") + tok = v.issue_token(scope="sign.api", context="api-test", max_uses=2) assert isinstance(tok, CapabilityToken) - with warnings.catch_warnings(): - warnings.simplefilter("ignore", DeprecationWarning) - assert v.consume(tok, "llm.evaluate") == "sk-test" + assert len(v.sign(tok, b"payload")) == 64 assert v.revoke(tok.token_id) is True assert v.audit_chain_valid() is True diff --git a/tests/test_silent_downgrades.py b/tests/test_silent_downgrades.py index 0521215..dd9c0a1 100644 --- a/tests/test_silent_downgrades.py +++ b/tests/test_silent_downgrades.py @@ -4,6 +4,7 @@ #13 invoke_llm fails closed off the Rust backend instead of leaking the key. #7 audit_chain_signed marks the unsigned fallback; strict_backend fails closed. #10 unseal() warns that the bootstrap crosses PyO3 as an un-zeroable str. + 2026-11-09: sign() fails closed off the Rust backend, as invoke_llm does. """ from __future__ import annotations @@ -29,6 +30,31 @@ def test_invoke_llm_fails_closed_off_rust_backend() -> None: v._backend_name = "python" with pytest.raises(CageViolation): asyncio.run(v.invoke_llm(tok, {"model": "m", "messages": []})) + # The refusal is on the chain, keyed on the validated token (Invariant 4). + refusals = [ + e for e in v.get_audit_log() if e["event"] == "invoke_refused_no_rust_backend" + ] + assert [e["entity_id"] for e in refusals] == [tok.token_id] + + +def test_sign_fails_closed_off_rust_backend() -> None: + """sign() keeps the key in Rust only on the Rust backend. Off it, the method + must refuse rather than read the key into Python to compute the HMAC.""" + v = SecretVault(insecure_dev_mode=True) + if v.backend != "rust": + pytest.skip("simulating the non-Rust path requires the Rust build present") + v.store_secret("hmac_key", "k") + v.register_scope_secret("sign.", "hmac_key") + tok = v.issue_token(scope="sign.x", context="t") + + v._backend_name = "python" + with pytest.raises(CageViolation): + v.sign(tok, b"payload") + refusals = [ + e for e in v.get_audit_log() if e["event"] == "sign_refused_no_rust_backend" + ] + assert [e["entity_id"] for e in refusals] == [tok.token_id] + assert not any(e["event"] == "signed" for e in v.get_audit_log()) def test_audit_chain_signed_marks_the_backend() -> None: diff --git a/tests/test_smoke.py b/tests/test_smoke.py index a346de5..cbbfa20 100644 --- a/tests/test_smoke.py +++ b/tests/test_smoke.py @@ -5,11 +5,28 @@ from __future__ import annotations +import hashlib +import hmac + import pytest from cage import CapabilityToken, CageViolation, SecretVault +def _rust_only(v: SecretVault) -> None: + if v.backend != "rust": + pytest.skip("the gated sign() op is Rust-backend only") + + +def _signing_vault() -> SecretVault: + """A dev vault with an HMAC key registered under the ``sign.`` namespace.""" + v = SecretVault(insecure_dev_mode=True) + _rust_only(v) + v.store_secret("hmac_key", "k-test-12345") + v.register_scope_secret("sign.", "hmac_key") + return v + + def test_backend_is_rust_or_python() -> None: v = SecretVault(insecure_dev_mode=True) assert v.backend in ("rust", "python") @@ -30,147 +47,86 @@ def test_store_and_token_lifecycle() -> None: assert token.remaining_uses() == 3 -def test_consume_increments_use_count() -> None: - v = SecretVault(insecure_dev_mode=True, allow_plaintext_consume=True) - v.store_secret("llm_api_key", "sk-test-12345") - token = v.issue_token(scope="llm.evaluate", context="t", max_uses=2) - - import warnings +def test_sign_increments_use_count() -> None: + v = _signing_vault() + token = v.issue_token(scope="sign.invoice", context="t", max_uses=2) - with warnings.catch_warnings(): - warnings.simplefilter("ignore", DeprecationWarning) - assert v.consume(token, "llm.evaluate") == "sk-test-12345" - assert v.consume(token, "llm.evaluate") == "sk-test-12345" + sig1 = v.sign(token, b"invoice #1") + sig2 = v.sign(token, b"invoice #1") + assert sig1 == sig2 + assert len(sig1) == 64 - # Third consume should raise — exceeded max_uses. - with pytest.raises(CageViolation): - v.consume(token, "llm.evaluate") + # The third use exceeds max_uses. + with pytest.raises(CageViolation): + v.sign(token, b"invoice #1") # The use counter is authoritative on the vault side, not on the caller's - # (frozen, stale) handle — verify the progression via the audit chain. - consumed = [e for e in v.get_audit_log() if e["event"] == "consumed"] - assert [e["data"]["use_count"] for e in consumed] == [1, 2] + # (frozen, stale) handle. Verify the progression via the audit chain. + signed = [e for e in v.get_audit_log() if e["event"] == "signed"] + assert [e["data"]["use_count"] for e in signed] == [1, 2] -def test_consume_refused_by_default() -> None: - # A vault at the shipped defaults must refuse consume() structurally — the - # plaintext-str leak path is opt-in only, so "no plaintext key in the agent" - # holds in production regardless of the deprecation. - v = SecretVault() +def test_wrong_operation_class_is_refused_and_audited() -> None: + # An llm.* token cannot drive sign(). The gate refuses before it resolves any + # secret, charges nothing, and records the refusal with the operation it saw. + v = SecretVault(insecure_dev_mode=True) + _rust_only(v) v.store_secret("llm_api_key", "sk-test-12345") - bootstrap = v.unseal() - token = v.issue_token( - scope="llm.evaluate", context="t", max_uses=1, bootstrap_token=bootstrap - ) + token = v.issue_token(scope="llm.evaluate", context="t", max_uses=1) with pytest.raises(CageViolation): - v.consume(token, "llm.evaluate") - # The refusal is on the chain, like every other refusal in the gate. - refused = [ - e for e in v.get_audit_log() - if e["event"] == "consume_refused_plaintext_disabled" - ] - assert len(refused) == 1 - assert refused[0]["entity_id"] == token.token_id - expected = {"scope": "llm.evaluate"} - if v.backend != "rust": - expected["layer"] = "facade" # the fallback's guard writes via the facade - assert refused[0]["data"] == expected - assert v.audit_chain_valid() - - -def test_core_refuses_consume_when_facade_guard_is_bypassed() -> None: - # The Rust core, not the facade flag, is the enforcement point: the facade - # attribute is not consulted on the Rust backend, so flipping it changes - # nothing — the core refuses and writes the refusal to the chain itself, and - # a refusal never emits the plaintext DeprecationWarning. - v = SecretVault() - if v.backend != "rust": - pytest.skip("the core guard is Rust-backend only") - v.store_secret("llm_api_key", "sk-test-12345") - bootstrap = v.unseal() - token = v.issue_token( - scope="llm.evaluate", context="t", max_uses=1, bootstrap_token=bootstrap - ) - v._allow_plaintext_consume = True # not consulted on the Rust backend - - import warnings - - with warnings.catch_warnings(): - warnings.simplefilter("error", DeprecationWarning) # a refusal must not warn - with pytest.raises(CageViolation): - v.consume(token, "llm.evaluate") - refused = [ - e for e in v.get_audit_log() - if e["event"] == "consume_refused_plaintext_disabled" - ] - assert len(refused) == 1, "written by the core — the facade guard was bypassed" - assert refused[0]["entity_id"] == token.token_id - assert refused[0]["data"] == {"scope": "llm.evaluate"}, "no facade layer tag" - - -def test_dev_switches_are_recorded_on_the_chain() -> None: - # A default vault's chain carries neither entry; a dev vault's chain says up - # front which waivers were on, before any token is issued under them. + v.sign(token, b"payload") + refusals = [e for e in v.get_audit_log() if e["event"] == "rejected_wrong_verb"] + assert len(refusals) == 1 + assert refusals[0]["entity_id"] == token.token_id + assert refusals[0]["data"] == {"scope": "llm.evaluate", "operation": "sign"} + assert not any(e["event"] == "signed" for e in v.get_audit_log()) + + +def test_sign_rejects_a_non_bytes_payload() -> None: + # bytes(5) is five zero bytes, so an int must not be coerced into a payload. + v = _signing_vault() + token = v.issue_token(scope="sign.invoice", context="t", max_uses=1) + with pytest.raises(TypeError): + v.sign(token, 5) # type: ignore[arg-type] + assert not any(e["event"] == "signed" for e in v.get_audit_log()) + # The refused call charged nothing: the single use is still available. + assert len(v.sign(token, b"ok")) == 64 + + +def test_no_operation_returns_a_stored_secret() -> None: + # The in-process surface has no call that hands a stored credential back to + # Python. The gated operations return a signature or a provider response. + for name in ("consume", "retrieve_secret", "get_secret", "decrypt_secret"): + assert not hasattr(SecretVault, name), f"SecretVault.{name} must not exist" + + +def test_dev_switch_is_recorded_on_the_chain() -> None: + # A default vault's chain carries no such entry. A dev vault's chain says up + # front that the waiver was on, before any token is issued under it. events = lambda v: [e["event"] for e in v.get_audit_log()] prod = SecretVault() if prod.backend != "rust": pytest.skip("switch audit is Rust-backend only") assert "insecure_dev_mode_enabled" not in events(prod) - assert "plaintext_consume_enabled" not in events(prod) - dev = SecretVault(insecure_dev_mode=True, allow_plaintext_consume=True) + dev = SecretVault(insecure_dev_mode=True) assert events(dev).count("insecure_dev_mode_enabled") == 1 - assert events(dev).count("plaintext_consume_enabled") == 1 assert dev.audit_chain_valid() -def test_insecure_dev_mode_alone_does_not_re_enable_consume() -> None: - # The two switches are decoupled: waiving control-plane auth must not also - # restore the plaintext path, or the escape hatch for one becomes the - # detonator for the other. - v = SecretVault(insecure_dev_mode=True) - v.store_secret("llm_api_key", "sk-test-12345") - token = v.issue_token(scope="llm.evaluate", context="t", max_uses=1) - with pytest.raises(CageViolation): - v.consume(token, "llm.evaluate") - - -def test_plaintext_consume_alone_does_not_waive_control_auth() -> None: - # The inverse direction of the decoupling: opting into the leak must not also - # waive the bootstrap requirement on issuance. - v = SecretVault(allow_plaintext_consume=True) - v.store_secret("llm_api_key", "sk-test-12345") - v.unseal() - with pytest.raises(CageViolation): - v.issue_token(scope="llm.evaluate", context="attacker") - - def test_non_bool_insecure_dev_mode_is_refused_not_coerced() -> None: - # Same rule for the other loosening switch: a truthy "false" must not waive - # control-plane auth on a vault its operator believes is fail-closed. - with pytest.raises(CageViolation): - SecretVault(insecure_dev_mode="false") # type: ignore[arg-type] - - -def test_non_bool_allow_plaintext_consume_is_refused_not_coerced() -> None: # A config- or env-sourced "false" is truthy in Python. Coercing it would - # silently enable the plaintext path on a vault its operator believes is + # silently waive control-plane auth on a vault its operator believes is # fail-closed, so construction refuses anything that is not a real bool. with pytest.raises(CageViolation): - SecretVault(allow_plaintext_consume="false") # type: ignore[arg-type] + SecretVault(insecure_dev_mode="false") # type: ignore[arg-type] -def test_revoke_blocks_consume() -> None: - v = SecretVault(insecure_dev_mode=True, allow_plaintext_consume=True) - v.store_secret("llm_api_key", "sk-test-12345") - token = v.issue_token(scope="llm.evaluate", context="t") +def test_revoke_blocks_sign() -> None: + v = _signing_vault() + token = v.issue_token(scope="sign.invoice", context="t") assert v.revoke(token.token_id) is True - - import warnings - - with warnings.catch_warnings(): - warnings.simplefilter("ignore", DeprecationWarning) - with pytest.raises(CageViolation): - v.consume(token, "llm.evaluate") + with pytest.raises(CageViolation): + v.sign(token, b"invoice #1") # --------------------------------------------------------------------------- @@ -178,21 +134,15 @@ def test_revoke_blocks_consume() -> None: # --------------------------------------------------------------------------- -def test_forged_token_rejected_by_consume() -> None: +def test_forged_token_rejected_by_sign() -> None: """A CapabilityToken the vault never issued must not unlock a secret, even though it is a public, constructable type (Invariant 6).""" - v = SecretVault(insecure_dev_mode=True, allow_plaintext_consume=True) - v.store_secret("llm_api_key", "sk-test-12345") + v = _signing_vault() forged = CapabilityToken( - scope="llm.evaluate", context="attacker", max_uses=999_999 + scope="sign.invoice", context="attacker", max_uses=999_999 ) - - import warnings - - with warnings.catch_warnings(): - warnings.simplefilter("ignore", DeprecationWarning) - with pytest.raises(CageViolation): - v.consume(forged, "llm.evaluate") + with pytest.raises(CageViolation): + v.sign(forged, b"invoice #1") log = v.get_audit_log() assert any(e["event"] == "rejected_unknown_token" for e in log) @@ -292,30 +242,30 @@ def test_audit_chain_detects_tampering() -> None: def test_unknown_scope_raises() -> None: - v = SecretVault(insecure_dev_mode=True, allow_plaintext_consume=True) + v = SecretVault(insecure_dev_mode=True) + _rust_only(v) v.store_secret("llm_api_key", "sk-test-12345") - token = v.issue_token(scope="kubernetes.deploy", context="t") - - import warnings - - with warnings.catch_warnings(): - warnings.simplefilter("ignore", DeprecationWarning) - with pytest.raises(CageViolation): - v.consume(token, "kubernetes.deploy") + # Nothing is registered under "sign.", so the scope resolves to no secret. + token = v.issue_token(scope="sign.deploy", context="t") + with pytest.raises(CageViolation): + v.sign(token, b"x") + assert any(e["event"] == "rejected_unknown_scope" for e in v.get_audit_log()) def test_register_scope_secret() -> None: - v = SecretVault(insecure_dev_mode=True, allow_plaintext_consume=True) - v.store_secret("aws_session_token", "ASIAEXAMPLE") - v.register_scope_secret("bedrock.", "aws_session_token") - - token = v.issue_token(scope="bedrock.invoke", context="t") - - import warnings + v = SecretVault(insecure_dev_mode=True) + _rust_only(v) + v.store_secret("release_key", "ASIAEXAMPLE") + v.register_scope_secret("sign.release.", "release_key") + token = v.issue_token(scope="sign.release.v1", context="t") - with warnings.catch_warnings(): - warnings.simplefilter("ignore", DeprecationWarning) - assert v.consume(token, "bedrock.invoke") == "ASIAEXAMPLE" + sig = v.sign(token, b"artifact") + # The signature was made with the registered secret, which never came back to + # Python. Recompute it here from the known test value. + expected = hmac.new(b"ASIAEXAMPLE", b"artifact", hashlib.sha256).hexdigest() + assert sig == expected + # A str payload is signed as its UTF-8 bytes. + assert v.sign(token, "artifact") == expected # --------------------------------------------------------------------------- @@ -501,18 +451,18 @@ def test_load_from_env_file_basic(tmp_path) -> None: def test_load_from_env_file_secret_recoverable(tmp_path) -> None: - """Verify the encrypted secret round-trips correctly via consume().""" + """The encrypted secret round-trips: a signature made with it equals one + computed from the known plaintext, and the secret never came back to Python.""" env_file = tmp_path / ".env" - env_file.write_text("llm_api_key=sk-roundtrip-99\n") - v = SecretVault(insecure_dev_mode=True, allow_plaintext_consume=True) - v.load_from_env_file(str(env_file), ["llm_api_key"]) - - token = v.issue_token(scope="llm.evaluate", context="t", max_uses=1) - import warnings + env_file.write_text("hmac_key=k-roundtrip-99\n") + v = SecretVault(insecure_dev_mode=True) + _rust_only(v) + v.load_from_env_file(str(env_file), ["hmac_key"]) + v.register_scope_secret("sign.", "hmac_key") - with warnings.catch_warnings(): - warnings.simplefilter("ignore", DeprecationWarning) - assert v.consume(token, "llm.evaluate") == "sk-roundtrip-99" + token = v.issue_token(scope="sign.check", context="t", max_uses=1) + expected = hmac.new(b"k-roundtrip-99", b"probe", hashlib.sha256).hexdigest() + assert v.sign(token, b"probe") == expected def test_load_from_env_file_missing_path(tmp_path) -> None: