Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand Down
187 changes: 5 additions & 182 deletions crates/cage-core/src/gate.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<String, Instant>,
Expand Down Expand Up @@ -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(),
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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<String, CageError> {
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) {
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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()
Expand All @@ -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());
}

Expand Down
17 changes: 0 additions & 17 deletions crates/cage-core/src/vault.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<String, CageError> {
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)
Expand Down
2 changes: 1 addition & 1 deletion python/cage/core/gate.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion python/cage/token.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading