diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e69ec260..6deca38e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -43,6 +43,11 @@ jobs: - name: cargo check working-directory: elastos run: cargo check --workspace + # Type-check the network-gated live-buy test so a rename can't silently rot the operator's + # only live tool (it stays #[ignore]d + feature-off in the gate; this never runs it). S45 F3. + - name: cargo check (live-chain test) + working-directory: elastos + run: cargo check -p elastos-server --features live-chain --tests test: name: Test @@ -58,6 +63,13 @@ jobs: run: cargo test --workspace # Network-sensitive tests are #[ignore] and won't run. # Run them explicitly with: cargo test --workspace -- --ignored + - name: cargo test (dev-modes lane) + working-directory: elastos + # The money-path construction ratchets (S43 typed BuyError, the S46 prepare-leg + # deadline, chain-mock buys) are `#[cfg(feature = "dev-modes")]` — without this lane + # the gate never compiles them, and a ratchet outside the gate cannot ratchet + # (council S46 guardian F3). Lib-only; shares the workspace build cache. + run: cargo test -p elastos-server --lib --features dev-modes build-release: name: Build Release (x86_64) diff --git a/README.md b/README.md index b7522cc7..d5e11391 100644 --- a/README.md +++ b/README.md @@ -212,6 +212,11 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), - device DID, passkey principals, wallet proof bindings, and Recovery Kit foundations without making wallet addresses the Runtime identity root - agent capsule with signed gossip and verified-only AI responses +- Flint mandates: grant an AI agent scoped, expiring, revocable authority (a mandate, not + your keys), watch and kill it from the Mandates shell app, let it spend real money under a + durable spend cap on a payment rail (HTTPS adapter or on-chain DRM marketplace), and export + a portable signed receipt verifiable off-box with `elastos verify-receipt` — see + [docs/FLINT_MANDATE_ENGINE.md](docs/FLINT_MANDATE_ENGINE.md) Important Browser status: the Browser ABI and hosted proof path are real, but the final product browser is not complete. Stable arbitrary-site media, accepted @@ -273,6 +278,8 @@ and release/docs slices. | [docs/CONTENT_AVAILABILITY.md](docs/CONTENT_AVAILABILITY.md) | SmartWeb content availability, IPLD-compatible manifests, and provider boundary | | [docs/WALLET_PROVIDER.md](docs/WALLET_PROVIDER.md) | Wallet, account, approval, proof, and signer/provider boundary | | [docs/CHAIN_PROVIDER.md](docs/CHAIN_PROVIDER.md) | Typed blockchain provider boundary | +| [docs/FLINT_MANDATE_ENGINE.md](docs/FLINT_MANDATE_ENGINE.md) | Flint — mandates for AI agents: scoped, revocable authority, spend-capped payments, portable signed receipts | +| [docs/DRM_MARKETPLACE_RAIL.md](docs/DRM_MARKETPLACE_RAIL.md) | The DRM marketplace payment rail (on-chain settlement under a mandate) | | [docs/BROWSER_CAPSULE.md](docs/BROWSER_CAPSULE.md) | Browser/Net/Exit/Engine ABI and current proof boundary | | [docs/BROWSER_PROVIDER_BAKEOFF.md](docs/BROWSER_PROVIDER_BAKEOFF.md) | Browser provider comparison and acceptance gates | | [docs/SITES.md](docs/SITES.md) | Local site hosting and public exposure | diff --git a/capsules/chain-provider/src/abi.rs b/capsules/chain-provider/src/abi.rs index 0220cac9..07219a6b 100644 --- a/capsules/chain-provider/src/abi.rs +++ b/capsules/chain-provider/src/abi.rs @@ -394,44 +394,41 @@ pub(super) fn decode_asset_created_log(entry: &Value) -> Option<(String, String, /// (a precise canonical `decode_mint_content_id`, else the relayer-safe `mint_input_binds_content_id` /// substring match). FAIL-CLOSED: `None` if no candidate binds the KID. Pure (no RPC) so it is /// unit-testable; the caller scans the `AssetCreated` logs + fetches each candidate's input live. -pub(super) fn pick_asset_created_binding_kid( +pub(super) fn collect_kid_bindings( decoded: &[(String, String, u64, u64, String)], inputs: &std::collections::HashMap, want_content_id: &str, -) -> Option<(String, String)> { - // Gather every candidate whose mint calldata binds the KID, split by strength: PRECISE = the - // canonical `mint` decode yields exactly this contentId; SUBSTRING = the relayer-safe fallback - // (the 16 content-derived KID bytes appear in the calldata). A unique asset has a unique KID, so - // in normal operation exactly ONE candidate binds. The AssetCreated scan is NOT creator-constrained - // (topic[1] is null), so a hostile co-channel minter could embed the victim's KID in their OWN mint - // calldata; we require a UNIQUE binding and FAIL CLOSED on ambiguity (>1 distinct (operative,tokenId) - // binding the same KID) rather than bind the wrong tokenId and mis-charge the buyer. Preferring the - // canonical decode means a substring-only hostile candidate cannot displace the precise legit one. - // (Creator-constraining the scan would also let us RESOLVE the legit asset under such griefing — the - // follow-on documented in protocol.rs; this pass fails closed, which protects funds.) - let mut precise: std::collections::BTreeSet<(String, String)> = std::collections::BTreeSet::new(); - let mut substring: std::collections::BTreeSet<(String, String)> = std::collections::BTreeSet::new(); +) -> std::collections::BTreeSet<(String, String)> { + // Return the UNION of every distinct (operative, tokenId) whose mint calldata BINDS the KID — + // by EITHER the canonical `decode_mint_content_id` (PRECISE) OR the relayer-safe + // `mint_input_binds_content_id` (SUBSTRING: the 16 content-derived KID bytes appear in the + // calldata). A unique asset has a unique KID, so in normal operation exactly ONE (operative, + // tokenId) binds. The AssetCreated scan is channel-scoped but NOT creator-constrained within the + // channel (topic[1] is null), so a hostile CO-CHANNEL minter can embed the victim's public KID in + // their OWN mint calldata. + // + // MKT-1 fix: we take the UNION of both methods and DO NOT prefer PRECISE over SUBSTRING. The old + // "prefer precise" rule let a hostile CANONICAL mint (precise) silently displace a legit RELAYED + // mint (which decodes only as substring) — binding the buyer to the attacker's tokenId. Surfacing + // BOTH binders lets the caller FAIL CLOSED on any resulting ambiguity (>1 distinct pair, here or + // across windows) rather than mis-charge the buyer. This trades availability (a griefer can block a + // resolve by minting a collision) for safety (funds are never bound to the wrong token) — the + // correct default on a money path. Pure (no RPC), unit-testable; the caller unions across ALL + // windows and requires GLOBAL uniqueness. + let mut bindings: std::collections::BTreeSet<(String, String)> = std::collections::BTreeSet::new(); for (operative, token_id, _block, _log, tx_hash) in decoded { let Some(input) = inputs.get(tx_hash) else { continue; }; - let is_precise = decode_mint_content_id(input) + let precise = decode_mint_content_id(input) .and_then(|cid| normalize_content_id_bytes16(&cid)) .as_deref() == Some(want_content_id); - if is_precise { - precise.insert((operative.clone(), token_id.clone())); - } else if mint_input_binds_content_id(input, want_content_id) { - substring.insert((operative.clone(), token_id.clone())); + if precise || mint_input_binds_content_id(input, want_content_id) { + bindings.insert((operative.clone(), token_id.clone())); } } - // Prefer the canonical decode; fall back to the substring binder only when no precise binder exists. - // In either tier a UNIQUE binding is required — otherwise fail closed. - let chosen = if precise.is_empty() { &substring } else { &precise }; - match chosen.len() { - 1 => chosen.iter().next().cloned(), - _ => None, // 0 binders, or an ambiguous KID binding -> fail closed (the buy must not proceed) - } + bindings } /// Decode the leading `bytes16` contentId (KID) from a `mint(string,uint16,bytes,bytes)` @@ -679,7 +676,7 @@ mod tests { } #[test] - fn pick_asset_created_binding_kid_matches_via_mint_calldata() { + fn collect_kid_bindings_binds_the_unique_asset() { use std::collections::HashMap; let kid = "9c2a000000000000000000000000e1a1"; let other = "00112233445566778899aabbccddeeff"; @@ -697,27 +694,25 @@ mod tests { let mut inputs = HashMap::new(); inputs.insert("0xaa".to_string(), mint_a); inputs.insert("0xbb".to_string(), mint_b.clone()); - // Hit: the KID resolves to candidate A's (operative, tokenId), proven by the mint calldata. - assert_eq!( - pick_asset_created_binding_kid(&decoded, &inputs, kid), - Some(("0xopA".to_string(), "0x07".to_string())), - ); - // Miss: an unknown KID -> None (fail closed; the buy must not proceed). - assert!(pick_asset_created_binding_kid(&decoded, &inputs, "deadbeefdeadbeefdeadbeefdeadbeef").is_none()); + // The KID binds exactly candidate A's (operative, tokenId) — a unique binding. + let b = collect_kid_bindings(&decoded, &inputs, kid); + assert_eq!(b.len(), 1); + assert!(b.contains(&("0xopA".to_string(), "0x07".to_string()))); + // Miss: an unknown KID -> empty (fail closed; the buy must not proceed). + assert!(collect_kid_bindings(&decoded, &inputs, "deadbeefdeadbeefdeadbeefdeadbeef").is_empty()); // Fail-closed: if the matching candidate's input is missing, it is skipped (no false bind). let mut partial = HashMap::new(); partial.insert("0xbb".to_string(), mint_b); - assert!(pick_asset_created_binding_kid(&decoded, &partial, kid).is_none()); + assert!(collect_kid_bindings(&decoded, &partial, kid).is_empty()); } #[test] - fn pick_asset_created_binding_kid_fails_closed_on_ambiguous_binding() { + fn collect_kid_bindings_surfaces_both_binders_in_one_window_so_caller_fails_closed() { use std::collections::HashMap; let kid = "9c2a000000000000000000000000e1a1"; - // Two AssetCreated candidates on the (creator-unconstrained) channel BOTH bind the same KID - // with DIFFERENT tokenIds — the legit asset (tokenId 7) and a hostile co-channel mint that - // re-uses the victim's KID (tokenId 0x66, newest). Binding either would mis-charge the buyer, - // so the resolver must FAIL CLOSED (None) rather than pick the newest candidate. + // Two AssetCreated candidates in ONE window BOTH bind the same KID with DIFFERENT tokenIds — + // the legit asset (tokenId 7) and a hostile co-channel mint re-using the victim's KID (0x66, + // newest). Both must SURFACE (set size 2) so the caller fails closed rather than pick newest. let legit = encode_mint_calldata("0x47cbeeb4", "ipfs://legit", 0, &encode_op_raw_free(kid).unwrap(), &[]) .unwrap(); @@ -731,9 +726,43 @@ mod tests { let mut inputs = HashMap::new(); inputs.insert("0xaa".to_string(), legit); inputs.insert("0xhh".to_string(), hostile); - assert!( - pick_asset_created_binding_kid(&decoded, &inputs, kid).is_none(), - "ambiguous KID binding must fail closed, not bind the newest (hostile) tokenId", + let b = collect_kid_bindings(&decoded, &inputs, kid); + assert_eq!(b.len(), 2, "both binders must surface so the caller fails closed"); + } + + // MKT-1 ratchet: the cross-window attack. A hostile mint in a NEWER window and the legit mint in + // an OLDER window each bind the victim's KID. The resolver accumulates bindings across ALL windows + // (never returns on the first) and requires GLOBAL uniqueness — so the union across windows has >1 + // distinct (operative, tokenId) and the buy FAILS CLOSED instead of binding the newer (hostile) + // token. This models `resolve_token_id`'s global fold with the pure per-window primitive. + #[test] + fn kid_bindings_across_windows_fail_closed_on_cross_window_collision() { + use std::collections::BTreeSet; + use std::collections::HashMap; + let kid = "9c2a000000000000000000000000e1a1"; + let legit = + encode_mint_calldata("0x47cbeeb4", "ipfs://legit", 0, &encode_op_raw_free(kid).unwrap(), &[]) + .unwrap(); + let hostile = + encode_mint_calldata("0x47cbeeb4", "ipfs://hostile", 0, &encode_op_raw_free(kid).unwrap(), &[]) + .unwrap(); + // NEWER window (scanned first): the hostile mint, tokenId 0x66. + let newer_decoded = vec![("0xopH".to_string(), "0x66".to_string(), 900u64, 0u64, "0xhh".to_string())]; + let mut newer_inputs = HashMap::new(); + newer_inputs.insert("0xhh".to_string(), hostile); + // OLDER window (scanned second): the legit mint, tokenId 0x07. + let older_decoded = vec![("0xopA".to_string(), "0x07".to_string(), 100u64, 0u64, "0xaa".to_string())]; + let mut older_inputs = HashMap::new(); + older_inputs.insert("0xaa".to_string(), legit); + + // The global fold = union of per-window binding sets (what resolve_token_id accumulates). + let mut global: BTreeSet<(String, String)> = BTreeSet::new(); + global.extend(collect_kid_bindings(&newer_decoded, &newer_inputs, kid)); + global.extend(collect_kid_bindings(&older_decoded, &older_inputs, kid)); + assert_eq!( + global.len(), + 2, + "a cross-window KID collision must fail closed globally, never bind the newer (hostile) token", ); } } diff --git a/capsules/chain-provider/src/main.rs b/capsules/chain-provider/src/main.rs index 7798f93d..05e88a89 100644 --- a/capsules/chain-provider/src/main.rs +++ b/capsules/chain-provider/src/main.rs @@ -1341,23 +1341,28 @@ impl ChainProvider { Err(response) => return response, }; let window = Self::max_log_range().max(1); - // Newest-first: an asset is minted before it can be listed, so walking down from the tip - // surfaces the match quickly and bounds RPC for the common (recent) case. + // MKT-1 fail-closed GLOBAL uniqueness: accumulate EVERY distinct (operative, tokenId) that + // binds the KID across the WHOLE channel range — we do NOT return on the first window — and + // bind ONLY if exactly one exists. A hostile co-channel mint that re-uses the victim's public + // KID (in the same OR a newer window) produces a second distinct binder, so the resolve fails + // closed rather than mis-charge the buyer. The channel-topic filter keeps the scan bounded to + // one channel's mints; the early-exit below caps the griefing/ambiguous path. + let mut found: std::collections::BTreeMap<(String, String), u64> = + std::collections::BTreeMap::new(); let mut to = latest; loop { let from = to.saturating_sub(window - 1).max(deploy_block); match self.scan_asset_created_window_for_kid(&network, &channel_topic, &want, from, to) { - Ok(Some((operative, token_id, block))) => { - return Response::ok(json!({ - "content_id": format!("0x{want}"), - "token_id": token_id, - "operative": operative, - "ledger": ledger, - "block": block, - "chain": network.id, - })); + Ok(hits) => { + for (operative, token_id, block) in hits { + found.entry((operative, token_id)).or_insert(block); + } + // Once two DISTINCT binders exist, more scanning cannot make the binding unique — + // fail closed now (also bounds RPC on the ambiguous/griefing path). + if found.len() >= 2 { + break; + } } - Ok(None) => {} Err(response) => return response, } if from <= deploy_block { @@ -1365,18 +1370,37 @@ impl ChainProvider { } to = from.saturating_sub(1); } - Response::error( - "token_id_not_found", - &format!( - "no AssetCreated on ledger {ledger} whose mint binds KID 0x{want} in [{deploy_block}, {latest}]" + match found.len() { + 1 => { + let ((operative, token_id), block) = found.into_iter().next().unwrap(); + Response::ok(json!({ + "content_id": format!("0x{want}"), + "token_id": token_id, + "operative": operative, + "ledger": ledger, + "block": block, + "chain": network.id, + })) + } + 0 => Response::error( + "token_id_not_found", + &format!( + "no AssetCreated on ledger {ledger} whose mint binds KID 0x{want} in [{deploy_block}, {latest}]" + ), ), - ) + _ => Response::error( + "ambiguous_kid_binding", + &format!( + "KID 0x{want} on ledger {ledger} binds >1 distinct (operative, tokenId) — refusing to bind a possibly-hostile token (buy blocked, fail-closed)" + ), + ), + } } /// Scan one window of the channel's `AssetCreated` logs (any creator), fetch each candidate mint /// tx's calldata, and return the `(operative, token_id, block)` whose mint binds the KID. Split-and- /// retry on a range-limit error (mirrors `fetch_asset_created_logs`); the pure bind is - /// `pick_asset_created_binding_kid`. + /// `collect_kid_bindings` (union of both bind methods; the caller requires global uniqueness). fn scan_asset_created_window_for_kid( &self, network: &ChainNetwork, @@ -1384,7 +1408,7 @@ impl ChainProvider { want_kid: &str, from: u64, to: u64, - ) -> Result, Response> { + ) -> Result, Response> { let filter = json!({ "fromBlock": format!("0x{from:x}"), "toBlock": format!("0x{to:x}"), @@ -1395,13 +1419,15 @@ impl ChainProvider { Err(response) => { if Self::is_range_limit_error(&response) && to.saturating_sub(from) >= MIN_LOG_RANGE { let mid = from + (to - from) / 2; - if let Some(hit) = self - .scan_asset_created_window_for_kid(network, channel_topic, want_kid, mid + 1, to)? - { - return Ok(Some(hit)); - } - return self - .scan_asset_created_window_for_kid(network, channel_topic, want_kid, from, mid); + // Concatenate BOTH halves — MKT-1 global uniqueness needs every binder, so a + // split-retry must never drop the lower half after a hit in the upper half. + let mut hits = self.scan_asset_created_window_for_kid( + network, channel_topic, want_kid, mid + 1, to, + )?; + hits.extend(self.scan_asset_created_window_for_kid( + network, channel_topic, want_kid, from, mid, + )?); + return Ok(hits); } return Err(response); } @@ -1423,22 +1449,40 @@ impl ChainProvider { // Fetch each candidate's mint calldata (live), then bind the KID purely. let mut inputs = std::collections::HashMap::new(); for (_, _, _, _, tx_hash) in &decoded { - if !inputs.contains_key(tx_hash) { - if let Some(input) = self.tx_input(network, tx_hash)? { + if inputs.contains_key(tx_hash) { + continue; + } + match self.tx_input(network, tx_hash)? { + Some(input) => { inputs.insert(tx_hash.clone(), input); } + // MKT-1 fail-closed-by-omission hardening: if a candidate mint's calldata cannot be + // fetched we CANNOT evaluate whether it binds the KID — silently skipping it could + // drop the legit binder and leave a hostile singleton (mis-bind). Abort the whole + // resolve rather than decide on a partial candidate set. + None => { + return Err(Response::error( + "candidate_input_unavailable", + &format!( + "mint calldata for candidate tx {tx_hash} is unavailable; refusing to resolve on a partial candidate set (fail-closed)" + ), + )); + } } } - let Some((operative, token_id)) = pick_asset_created_binding_kid(&decoded, &inputs, want_kid) - else { - return Ok(None); - }; - let block = decoded - .iter() - .find(|entry| entry.1 == token_id && entry.0 == operative) - .map(|entry| entry.2) - .unwrap_or(from); - Ok(Some((operative, token_id, block))) + // Return ALL distinct binders in this window (with a representative block) — the caller folds + // them across windows and requires GLOBAL uniqueness (MKT-1 fail-closed). + let bindings = collect_kid_bindings(&decoded, &inputs, want_kid); + let mut hits = Vec::with_capacity(bindings.len()); + for (operative, token_id) in bindings { + let block = decoded + .iter() + .find(|entry| entry.1 == token_id && entry.0 == operative) + .map(|entry| entry.2) + .unwrap_or(from); + hits.push((operative, token_id, block)); + } + Ok(hits) } /// Discover a creator's dDRM channels via a PERSISTED, RESUMABLE factory scan. Mirrors diff --git a/capsules/mandates/capsule.json b/capsules/mandates/capsule.json new file mode 100644 index 00000000..74449966 --- /dev/null +++ b/capsules/mandates/capsule.json @@ -0,0 +1,14 @@ +{ + "schema": "elastos.capsule/v1", + "name": "mandates", + "version": "0.1.0", + "description": "See the mandates you have granted to AI agents — scoped, expiring, revocable authority — and open a portable, independently-verifiable receipt of exactly what each agent did. Give your agent a mandate, not your keys.", + "role": "app", + "type": "data", + "author": "elastos", + "entrypoint": "index.html", + "resources": { + "memory_mb": 32, + "gpu": false + } +} diff --git a/capsules/mandates/index.html b/capsules/mandates/index.html new file mode 100644 index 00000000..c33d9a7a --- /dev/null +++ b/capsules/mandates/index.html @@ -0,0 +1,1154 @@ + + + + + + + +Flint — Mandates + + + + +
+
+
+ +
+

Flint — Mandates

+
Give your agent a mandate, not your keys.
+
+
+
+ Runtime signer + — + +
+
+ + + +
+ +
+

Standing mandates

+ durable across restarts — revoked ones stay listed + +
+ + + +
+ + + + + + + + + + + + + + + + +
+ A mandate is a scoped, expiring, revocable grant to one agent key. Its receipt is a portable, + set-bound bundle anyone can verify off-box — no runtime, no trust in this box. +
+
+ +
+ + + + + diff --git a/docs/AUDITOR_PACKET.md b/docs/AUDITOR_PACKET.md index db459aa2..3ab43f56 100644 --- a/docs/AUDITOR_PACKET.md +++ b/docs/AUDITOR_PACKET.md @@ -156,3 +156,49 @@ checklist, and the code ever disagree about the §1 invariant, it should fail. - [ ] Confirm `Debug` redaction (§4) covers all CEK / escrow-bearing structs. - [ ] Note any second consumer of the node re-seal output anywhere in the tree (should be none). - [ ] Spot-check the §4b verdict registries against the code and confirm the scope-out is sound. + +--- + +## 7. Second engagement scope — the Flint mandate/money plane (added S52) + +Since this packet was first cut, the runtime grew a second audit-worthy plane: **Flint** — agents +acting under scoped, revocable, cryptographically provable mandates, including REAL payments. +Design + honest bounds: [FLINT_MANDATE_ENGINE.md](FLINT_MANDATE_ENGINE.md). Wire formats a +verifier can implement from the documents alone: [SPEC-mandate-v1.md](SPEC-mandate-v1.md) +(mandate + receipt + signed-intent bytes, pinned by byte-identity conformance ratchets) and +[SPEC-market-provider-v1.md](SPEC-market-provider-v1.md) (the payment-vertical contract, proven +non-DRM-shaped by two shipped verticals). Gap ledger: [KNOWN_GAPS.md](KNOWN_GAPS.md) (the honesty +document — every open residual is listed there, none silently). + +**The invariants we are asking a reviewer to attack** (each enforced by construction + ratcheted): + +1. **Money never exceeds the mandate.** Cap reservation precedes any rail call (`SpendMeter`, + durable, single-opener Unix advisory flock); two-generals classification is decided by CODE PATH, never by + error text (`BuyError`/`PayError` typed at the call site — no provider-controlled byte can flip + refund vs hold); chain-settled buys are `Pending` at broadcast and charge only after + depth-gated confirmation; the record-before-broadcast ledger custody means a re-dispatch can + never double-move value (signature-derived idempotency keys, money-bearing keys never evicted). +2. **The receipt chain is the accountability artifact.** Per-record ed25519 (`verify_strict`) + + SHA-256 hash chain + set-binding; exported `MandateReceipt`s verify OFF-BOX via the standalone + `elastos verify-receipt` CLI with a pinned issuer key; settlement references (`rail_ref`) are + signed fields — editing one flips AUTHENTIC → INVALID. +3. **The audit plane survives crash + concurrency.** S51 group commit: `emit` returns `Ok` only + after ITS record is fsynced; failed durability POISONS the log (never a duplicate-seq retry); + a torn never-acknowledged tail is quarantined at open, never bricking the durable prefix; the + head anchor floors tail-truncation; single-opener flock (S52). Bench: + `cargo bench -p elastos-runtime --bench audit_emit` (verifies the chain it measures). +4. **The agent is confined by the envelope, not by trust.** Signed intents (domain-separated, + freshness-checked, replay-guarded), per-mandate rate budgets, agent-key binding, operator + kill-switch (revoke is fail-closed: the signed revoke event lands before the token dies), + liability DID on grant + receipt, quote/negotiate/pay all scoped to the granted resource. + +**Method note for the engagement:** every sprint since S27 shipped through a two-seat adversarial +internal council (principles-guardian + red-team) whose findings were folded with reproducing +ratchet tests — the commit history on this branch records each verdict and fold. That is internal +review, not independent assurance; it should make the external pass cheaper (the ratchets are the +scope-out registry), not replace it. + +Reproduce the state: the S46-truthful gate is `cargo test -p elastos-server --lib` (default + +`--features dev-modes`), `--bin elastos`, `-p elastos-runtime --lib`, `-p elastos-common --lib`, +`cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets -- -D warnings` — all green +at every sprint boundary. diff --git a/docs/AUDIT_2026-07-03.md b/docs/AUDIT_2026-07-03.md new file mode 100644 index 00000000..9558f20f --- /dev/null +++ b/docs/AUDIT_2026-07-03.md @@ -0,0 +1,105 @@ +# flint-0.5 — 0.01% Audit & Roadmap (2026-07-03) + +A six-seat adversarial audit of the `flint-0.5` branch: what the system is, how +good it is, and the roadmap ordered by what most raises interest and opens +revenue per unit effort. Each seat read the real code and docs; the synthesis +was stress-tested by a completeness critic. + +## Scorecard + +| Dimension | Grade | One-line | +|---|---|---| +| Capability Security | **8/10** | Enforcement spine is genuinely fail-closed; residual risk is in peripheral planes, honestly tracked | +| Cryptography & DRM | **8/10** | Post-quantum hybrid seal + threshold dKMS + transcript-AAD binding are sound; exposure is dependency maturity + the inherent client-side ceiling | +| Mission & Architecture | **7/10** | Clean primitives; the trusted core is inverted (170k-line server vs 24k runtime) and the reach/enforcement halo is built-but-unwired | +| Code Quality | **7/10** | Excellent build-visible ratchet culture; two god-files + a stringly-typed mint path drag it | +| Product & Monetization | **6/10** | Real moat, but it lives in the pre-release runtime while revenue runs on the legacy stack; zero published traction | +| Performance & Scalability | **5/10** | The audit fsync-per-record ceiling is real and, by the codebase's own admission, never benchmarked | +| **Overall** | **≈7/10** | Exceptional cryptographic + capability core; unfinished enforcement edges; pre-revenue | + +## Mission (derived from the code) + +Elacity is a **capability-security kernel + decentralized post-quantum DRM for +the agent economy**. It lets a creator encrypt any asset once, mint tradeable +rights on-chain, and let a buyer *open it inside a containment boundary where the +bytes and the key never escape* — and it can **prove**, with a tamper-evident +receipt, what a fooled human-or-agent principal was allowed to touch. It matters +because the AI era needs two things incumbents cannot provide: authority that is +*enforced*, not logged; and a way to sell AI models and data **without handing +over the weights** — a category only the capsule model can serve. + +## The through-line all six seats circled + +- **The core is real and rare** (security 8, crypto 8): 10-step fail-closed + validate with exact-action equality; ML-DSA-65 / ML-KEM-768 hybrid CEK seal; + 2-of-3 threshold dKMS with real DKG/resharing; downgrade-resistant hash-chained + audit. This is fundable *technology*. +- **The differentiators are unbuilt or unwired**: the reach/"halo" enforcement + model (`elastos-common/src/reach.rs`) is referenced nowhere; the user-approval + *act* path is stubbed (`gateway_capsule_catalog.rs`); Tier-3 sandboxed execute + and attested-TEE nodes are design docs. +- **The business is pre-evidence** (product 6): today's revenue runs on the + *legacy* stack; this runtime is "review candidate, not production"; zero + published traction by policy. + +## Two framing corrections the swarm produced + +- **T7 is not the crypto risk.** The pre-release `ed25519-dalek 3.0-pre` is an + aliased package used **only** by the DHT peer-discovery plane; the token / + audit / identity spine uses stable `ed25519-dalek 2.x`. The **actual** + crypto-critical dependency is the pre-1.0 `ml-dsa 0.1` / `ml-kem 0.2.3` PQ + crates that protect every key — pin + KAT-test those against FIPS 203/204. +- **"Decentralized" is aspirational today.** The 2-of-3 quorum runs in one + operator trust domain; confidentiality holds only if ≤1 node is adversarial. + State that boundary honestly before any sovereignty claim. + +## Roadmap — ordered by (fundability × de-risk) ÷ effort + +### NOW — de-risk the money path + manufacture the first evidence +1. **Fix MKT-1 + ratchet** *(med)* — HIGH on-chain-reachable mis-bind; blocks any + honest marketplace claim. **DONE 2026-07-03** (fail-closed global uniqueness). +2. **Close the one live buy; publish a single named-creator, receipt-backed sale** + *(med)* — turns the honesty discipline into the first metric. +3. **Type the mint/buy error surface (`MintError` enum)** *(low)* — kills a silent + 400→502 trap on the money path; one-file blast radius. **DONE 2026-07-03.** +4. **Add the first benchmark (audit + validate)** *(low)* — converts the perf story + from estimate to fact. **DONE 2026-07-03** (`benches/audit_emit.rs`): measured + ~879k memory-only vs ~789 durable emits/s (fsync-per-record) — a ~1113× custody + tax; quantifies the group-commit ceiling (would lift ~789/s → ~789×K). + +### NEXT — reframe the category + earn the technical claim +5. **Ship ONE Tier-3 "sell a runnable AI model, buyer never sees the weights" + demo** *(high)* — *the* fundraising centerpiece; reframes from "2%-vs-45% DRM + marketplace" to a category only the capsule model can serve. +6. **Package AI-training-rights licensing** (likeness/voice/datasets — the creator + app already captures the metadata) *(med)*. +7. **Wire the reach/egress model into policy + gateway; unstub the user-approval + act path** *(med)* — makes "enforce, not log" *true* instead of self-declared. +8. **Pin + KAT-test the PQ crates against FIPS 203/204 vectors** *(med)* — the real + crypto-critical dependency. + +### LATER — scale + make "decentralized" honest +9. Audit group-commit rewrite — *after* the benchmark (measure-first) *(med)*. +10. Diversify dKMS nodes out of one trust domain + recover-proof↔reseal-AAD + binding + external audit-chain anchoring *(high)*. +11. Carrier peer authentication (G-CARRIER-PEER) *(high)*. +12. Extract the god-files + shrink the trusted core (ADR-0001) *(high, ongoing)*. + +## Adversarial critique — what a skeptical investor/CTO will attack + +- **"You're raising on the moat you haven't built."** Cash runs on the legacy + stack; item 5 is the answer and it's high-effort — sequence ruthlessly. +- **"Zero traction, by policy."** Item 2 is the minimum viable proof. +- **"'Sovereign/decentralized' is aspirational."** State the honest trust boundary + (item 10) before claiming it, or lose credibility in technical diligence. +- **"Unbreakable DRM? No."** Any authorized viewer can screen-capture. Position as + *raise cost + trace + gate release + sell-what-can't-be-copied (Tier-3)*. +- **"Scalability with zero benchmarks."** Benchmark (item 4) before any throughput + claim. + +## The one thing + +Ship a single **Tier-3 "runnable model, weights never leave the capsule"** demo. +It is the only move that converts this from "another DRM marketplace" into a +category incumbents structurally cannot copy — and it monetizes the exact moat the +architecture already supports. diff --git a/docs/CODE_QUALITY_LEDGER.md b/docs/CODE_QUALITY_LEDGER.md new file mode 100644 index 00000000..4341e3d5 --- /dev/null +++ b/docs/CODE_QUALITY_LEDGER.md @@ -0,0 +1,26 @@ +# Code-quality ledger — deferred structural cleanups (Flint) + +The 2026-07 four-seat quality audit (money spine, dispatch surface, receipt primitives, +docs/presentability) folded every small-and-safe finding directly (shared sentinel consts, the +ledger admission helper, whole-record rollback, frozen-serialization docs on `AuditEvent`, the +shared canonicalization recipe, env-lock ordering, doc restructuring — see the audit commit). +The findings below are REAL but structural — multi-day, behavior-preserving refactors that +deserve their own gated increments rather than a rushed fold. Honest status: none of these is a +correctness bug; all fail in the safe direction today. + +| # | Area | Finding | Shape of the fix | +|---|---|---|---| +| CQ-1 | `api/handlers/capability.rs` (6.3k lines) | Four separable products in one file: consent-request flow, mandate lifecycle + dispatch, money provisioning/reconciliation, and a 3.8k-line test module | Split into `capability.rs` / `mandates.rs` / `money.rs` with re-exports through `handlers`; pure code motion | +| CQ-2 | `dispatch_standing_intent` (~335 lines) | Eight pipeline stages whose ordering invariants live in prose comments; three `Arc` side channels smuggle executor results | Named per-stage helpers returning `Result<(), (StatusCode, String)>` + one `ExecSideChannel` struct; ~40-line orchestrator | +| CQ-3 | Test fixtures (capability.rs, intent_executor.rs, manager.rs, gateway_mandates.rs) | The 8-field `IssueStandingGrantInput` literal ×~25, five near-identical state constructions, six `IntentDeclarationV1::issue` scaffolds, ~30 copy-pasted `validate()` calls | `#[cfg(test)]` builders (`grant_input`, `signed_intent`, `state_with_rail`) collapsing each test to its intent | +| CQ-4 | Error types at seams | `(StatusCode, String)` across ~40 handlers; `AuditError::Serialize(String)/Io(String)`; `verify_chain -> Result`; three coexisting handler-error styles | One crate-internal `ApiError { status, code, message }: IntoResponse`; structured `ChainVerifyError` variants with identical `Display` texts | +| CQ-5 | `capability/intent.rs` (3.6k lines) | Seven jobs in one module (records, envelope, gate, store + migrations, dispatcher, service, tests) | Split into `intent/{records,envelope,gate,store,service}.rs` with a re-exporting `mod.rs`; pure code motion | +| CQ-6 | flock + atomic-snapshot persistence | The single-opener flock block and tmp+fsync+rename discipline exist in `SpendMeter`, `PaymentLedger`, and `StandingGrantStore`, already drifted (the ledger lacks the pre/post-publish split) | Shared `acquire_single_opener` / `write_snapshot_atomic` helpers in a common crate; each store keeps its own rollback/poison policy | +| CQ-7 | `primitives/audit.rs` read surface | Six hand-rolled open-log→parse-`ChainedRecord` loops with divergent error handling; receipt exporters swallow I/O errors into `None` (`.ok()?`) | One `chained_records(path)` iterator; exporters return `Result, AuditError>` | +| CQ-8 | `event_type_name` (30 arms) | Hand-maintained mirror of serde's tag strings; a drifted arm silently breaks event filtering | Exhaustive test asserting `event_type_name() == serde_json::to_value(ev)["type"]` for every variant (or generate via serde) | +| CQ-9 | Sprint/council archaeology in comments | Ticket-style IDs ("council S29 G-F8", "chunk 2c-gw-A") bury real invariants for outside readers | Keep the constraint sentence, cite the decision log once per module; targeted sweep, never touching serialized fields | +| CQ-10 | Misc | `content_open`'s 7 positional params (+stringly `"opened"/"denied"`); `BuyOutcome.unsigned_tx` misnamed in wallet-signed modes; `with_file_handle` test seam is plain `pub`; double serialization per audit emit; `mandate_cmd.rs` display shaping untested; chain-tx helpers re-resolve the binary per call | Params struct + `Decision` enum; rename/re-doc `tx_view`; `#[doc(hidden)]`; `RawValue` single-serialize; extract + unit-test display shaping; thread a `LiveChain` struct | + +Rule for closing an entry: the refactor ships in its own commit with the full gate green and, where +the entry names a drift risk, a ratchet test that pins the invariant (CQ-8's exhaustive test is the +model). Delete the row when it lands. diff --git a/docs/DRM_MARKETPLACE_RAIL.md b/docs/DRM_MARKETPLACE_RAIL.md new file mode 100644 index 00000000..326634d5 --- /dev/null +++ b/docs/DRM_MARKETPLACE_RAIL.md @@ -0,0 +1,240 @@ +# The Flint DRM Marketplace Rail (Sprint 34 — the wedge) + +**Audience:** an operator wiring a Flint runtime to buy Elacity DRM assets on-chain, and the +engineer maintaining the seam. This is the payment rail where **the marketplace IS the rail**: a +`runtime.pay` act whose payee names a DRM asset settles on-chain via the Elacity `buy_authority` +path instead of an HTTPS POST — under the same mandate → spend cap → receipt spine as every other +Flint payment. + +## What it is + +The runtime already held both halves of one transaction, unconnected: + +- **Flint's `runtime.pay` affordance** — a mandate authorizes an agent to spend, a durable spend + meter caps it, and a portable receipt records the act. +- **The Elacity v3 DRM bindings** — `buy_authority` → AuthorityGateway on Base, ERC-1155 + ACCESS_TOKEN, on-chain royalty settlement. + +`DrmMarketplaceProvider` joins them behind the **same `PaymentProvider` trait** the HTTPS rail +implements, so the meter, the ledger, the two-generals classification, and the signed receipt are +**byte-identical whichever rail is wired** (one pay spine, never a fork). + +## How to wire it + +``` +ELASTOS_PAYMENT_RAIL=drm # select the DRM rail (wins over ELASTOS_PAYMENT_ENDPOINT) +ELASTOS_DRM_BUYER_PRINCIPAL= # REQUIRED in practice: the buyer principal (its linked EVM + # wallet, or the managed account in wallet-signing mode). + # The rail wires without it (boot warning) but every buy + # then fails closed until it is set. +ELASTOS_DRM_BUYER_SUBJECT= # optional explicit EVM address; empty ⇒ managed account +ELASTOS_DDRM_LEDGER= # REQUIRED in practice: the ledger the KID→tokenId scan + buy + # consult. (Yes, `DDRM` — the historical dDRM prefix, same + # family as the other ELASTOS_DDRM_* vars; NOT a typo of + # "ELASTOS_DRM_LEDGER", which the code does not read.) +ELASTOS_DRM_SPEND_UNIT= # REQUIRED (live Chain rail): pay-token smallest-units per ONE + # spend unit — e.g. 1000000 for USDC (6 decimals) ⇒ 1 spend + # unit == 1 USDC. The price gate uses this to compare the + # mandate cap against the on-chain price IN THE SAME UNIT. +ELASTOS_DRM_PAY_TOKEN= # REQUIRED (live Chain rail): the pay-token address the unit + # above denominates — a listing quoting any other token is + # refused before broadcast (the cap is one token's ceiling). +ELASTOS_DRM_MIN_CONFIRMATIONS= # optional confirmation-depth floor (default 3) +ELASTOS_DRM_RECONCILE_INTERVAL_SECS= # optional: ARM the in-runtime confirmation scheduler + # (Sprint 37) — every N seconds, pending DRM buys are polled + # and promoted/refunded/held. OFF when unset (no ambient + # background chain poller); a malformed value refuses to arm. +ELASTOS_DRM_RECONCILE_BATCH= # optional per-tick cap on pendings processed (default 64, + # oldest-first; the overflow is counted and picked up next + # tick). A malformed value refuses to arm. +ELASTOS_CHAIN_READ_DEADLINE_SECS= # optional (Sprint 40, default 30): the hard deadline on + # ONE chain-provider conversation — a hung provider is + # killed (process group and all). Any value <1 (or a typo) + # is treated as malformed => the default, loudly (the + # protection never silently disappears). Set it ABOVE your + # P99 RPC roundtrip: too low forces every live buy + # Indeterminate (a self-inflicted availability cliff), the + # safe money direction but a real outage. +``` + +The DRM rail **requires the durable spend meter + ledger** (real money on non-durable stores is +refused — `runtime.pay` stays UNWIRED, fail-closed) AND, on the live **Chain** rail, an explicit +`ELASTOS_DRM_SPEND_UNIT` (Sprint 36): without a declared meter-unit⇄pay-token mapping the rail +**refuses to wire** rather than silently assume 1 spend unit == 1 wei — so the cap is a literal +on-chain ceiling **in the declared pay-token unit** (Honest bounds 1), not just intent. The live rail +ALSO requires `ELASTOS_DRM_PAY_TOKEN` (the token the unit denominates): a listing quoting any other +token is refused before broadcast. (In the Dev/chain-mock rights modes the quote returns price 0, +so the price gate never rejects there.) Provision caps exactly as for any rail: +`POST /api/spend-budgets` (or the Mandates Money panel). + +## How a payment's state reads across the three surfaces + +The rail, the ledger, and the dispatch response each speak their own vocabulary for the same +moment in a buy's life. The map: + +| Moment | Rail outcome | Ledger entry | Dispatch reports | +|---|---|---|---| +| Refused before broadcast (over cap, ambiguous KID, sold out, drift, wrong pay-token) | `NotCharged` (refund) | `NotCharged` (terminal) | `authorized_not_performed`, reason names the refusal | +| Broadcast accepted, not yet confirmed | `Indeterminate` (reservation held) | `Pending` | `authorized_not_performed` — **a successful broadcast still reads as not-performed**, because performed is reserved for chain-confirmed truth | +| Confirmed at the depth floor | (reconciliation) | `ResolvedCharged` + receipt `rail_ref` | the receipt's pay-use row now carries the confirmed tx | +| Reverted on-chain | (reconciliation) | `ResolvedNotCharged`, reservation refunded once | — | + +The payee of a buy intent is the **DRM asset reference** (the KID / content id) — the suffix of the +pay resource `elastos://runtime/pay/`. The signed `input_hash` carries the amount in spend +units, as always. + +## What it does, step by step + +1. **Resolve** the asset reference to its unique on-chain binding via the **MKT-1-hardened** + resolver (`chain_tx::resolve_token_id`): it accumulates every distinct `(operative, tokenId)` + across the channel range and binds ONLY when exactly one exists. An ambiguous KID is **fail-closed + refused** (`NotCharged` → the reserved cap is refunded), **never a fallback buy**. +2. **Quote** the on-chain price + pay-token READ-ONLY (`buy_authority::quote_buy`, no broadcast), + then **PRICE-GATE**: the mandate cap `amount × ELASTOS_DRM_SPEND_UNIT` (pay-token units) MUST + cover the on-chain `price` — else refuse before broadcast (`NotCharged`/refund), never buy above + what the mandate authorized. Fail-closed on an unparseable price or a conversion overflow. +3. **Settle** the buy for the pinned binding via `buy_authority::buy_access`, binding the GATED + price as the expected price so the buy's own **abort-on-drift** aborts if the live price changed + between the quote and the broadcast (the buy can never settle above the gated price). +4. **Classify** the outcome two-generals-honestly (Sprint 35 — confirmation-aware): + - the buy path reported a BROADCAST-ACCEPTED tx ⇒ `Indeterminate`, filed as a **PENDING** ledger + entry with the reservation HELD and the tx recorded in the `rail_ref`. A DRM buy is **never** + recorded charged/`Performed` at broadcast — `buy_access` returns at `eth_sendRawTransaction` + acceptance, not inclusion. + - provably never broadcast (wallet unlinked, listing sold out, price-drift abort) ⇒ `NotCharged` + — refund the cap. + - the send returned no tx handle (RPC timeout) ⇒ `Indeterminate` with no tx — reservation held, + resolved out of band by the intent-signature idempotency key. +5. **Confirm, then record the on-chain truth.** `reconcile_drm_confirmations` polls each pending DRM + tx (`eth_getTransactionReceipt` + a confirmation-depth floor, `ELASTOS_DRM_MIN_CONFIRMATIONS`, + default 3) — driven UNATTENDED by the in-runtime scheduler when + `ELASTOS_DRM_RECONCILE_INTERVAL_SECS` is set (Sprint 37), or manually via the reconcile + surface: **mined + successful + deep enough** ⇒ promote to charged (spend stands) AND bind + `rail_ref = drm:tx=;op=;tid=;price=;tok=` onto the + signed `CapabilityUse` and thus + the portable receipt; **reverted** ⇒ refund the reservation exactly once; **not-yet-mined / below + the floor / RPC unreachable** ⇒ leave Pending, never auto-charge. So `elastos verify-receipt` + shows WHICH tx the chain **confirmed** for the mandate's payment — not merely what the rail + broadcast — verifiable off-box. + +**On-rail idempotency (Sprint 35).** The durable ledger is the dedup: the pay path refuses to +re-charge a signature-derived key that already carries a money-moved-or-may-have entry +(`Performed`/`Pending`/`ResolvedCharged`), so a re-dispatched identical signed intent past the +replay window resolves to the SAME buy — never a second one. + +## The confirmation scheduler (Sprint 37 — unattended resolution) + +With `ELASTOS_DRM_RECONCILE_INTERVAL_SECS` set on a DRM-wired rail, the runtime itself drives +pending buys to their terminal verdicts — no operator loop required. The scheduler is a thin +timer over the SAME `reconcile_drm_confirmations` pass the manual path runs (zero new +money-moving code; one spine), with these properties: + +- **Off by default.** No interval declared ⇒ no background chain poller, ever. An interval on a + non-DRM rail warns and stays off. A malformed interval or batch REFUSES to arm — the scheduler + never guesses its own cadence or bound. +- **Fail-closed on every failure mode.** An unreachable RPC, an unscripted verdict, a reconcile + error, or a PANIC on one entry all resolve to the same outcome: that entry stays Pending and is + retried next tick. A tick can promote (at the depth floor), refund (a revert, exactly once), or + hold — nothing else. +- **Bounded, rotating, and idempotent.** At most `ELASTOS_DRM_RECONCILE_BATCH` pendings per tick; + the overflow is counted, never silently dropped, and a ROTATING cursor starts each tick after + the previous tick's last entry (wrapping), so every pending is visited within + ceil(pending/batch) ticks — a stuck-unconfirmed prefix can never starve the entries behind it. + Re-polling an already-resolved entry is a no-op by the ledger's resolve-exactly-once rule; + overlapping or manual passes cannot double-resolve. +- **Observable and provable.** A tick that SETTLED anything (promoted or refunded) appends a + `drm_reconcile_tick` event (promoted/refunded/left_pending/skipped) to the signed chain — + best-effort: a failed append is logged and never blocks the tick; the per-entry + `payment_reconciled` events remain the durable money attestation. A promoted entry carries the + same `rail_ref` a manual reconcile would bind — byte-identical, because it IS the same path. + Idle and held-only ticks are silent, so a stuck pending cannot grow the signed chain by one + event per tick. +- **Never starves or wedges the runtime.** Ticks run on the blocking pool; a slow RPC delays the + next tick (no catch-up bursts), and at most ONE tick is ever in flight — if a tick is still + running when the next interval fires, the scheduler logs loudly and skips (a hung chain-provider + read cannot wedge the schedule or stack blocked threads; entries stay safely Pending). + The chain-provider read itself carries a hard deadline (Sprint 40, + `ELASTOS_CHAIN_READ_DEADLINE_SECS`, default 30s): a hung provider is killed — process group and + all — so no thread ever parks past the deadline on any ONE chain-provider conversation (a full + op may traverse a few conversations, each separately bounded). A deadline on a SEND leg + classifies INDETERMINATE (the tx may have broadcast — hold, reconcile), never a refund; + deadlines on read legs (resolve/quote/receipt) are ordinary fail-closed refusals/holds. + The wallet-provider SIGN leg and the rights-provider DECIDE leg carry the SAME deadline + (Sprint 41 — one shared `capsule_watchdog`): a hung signer or rights capsule is killed too (the + kill is unix-only, like the flock protections; elsewhere the watchdog is a stated no-op and the + old unbounded behavior remains). A wallet SIGN timeout is a PRE-broadcast refusal (the tx was + never signed ⇒ NotCharged/refund — the mirror of the send-leg rule); a rights DECIDE timeout + DENIES access (fail-closed). With this, every **chain-read, wallet-sign, and rights-decide** + provider conversation the pay/access pipeline traverses is bounded — including the reap (an + answered-then-lingering child is group-killed after a short grace, not parked on `wait()`). + The access-path *sidecar* helpers outside these three provider conversations (the + protected-content open/view relays — the media/object authorities and the grant sidecar) are now + bounded too (Sprint 42 — same shared `capsule_watchdog`): a hung content-authority is + group-killed at the deadline and the open/view is DENIED (fail-closed, the mirror of the + rights-decide rule; never a money decision, since these sit on the open/view paths, not the pay + spine). Proven by `object_authority::a_hung_object_authority_is_killed_and_access_is_denied`, + `media_authority::a_hung_media_authority_is_killed_and_access_is_denied`, and + `access_grant::a_hung_grant_sidecar_is_killed_and_the_open_fails_closed`. + +## Watching it (the Marketplace panel + the demo) + +The Mandates shell app's **Marketplace panel** (Sprint 38) shows this rail's state read-only: the +assets your active pay-mandates scope (live price/pay-token/supply via the read-only quote path — +TTL-cached per asset, single-flight, fan-out-bounded per view), and the buys as the ledger records +them — every PENDING buy always shown, the settled tail windowed with the window stated — in the +state vocabulary of the table above. Outside the live Chain rights mode the panel says quotes are +free/synthetic rather than displaying them as on-chain prices. The panel has NO buy verb — buys +happen only through an agent's signed intent. + +Agents shop the same way (Sprint 39): `runtime.market_quote` is a READ affordance behind the +same dispatch gate — an agent granted a `read` quote-mandate on a pay resource may quote THAT +asset's live terms (price/pay-token/supply) through the identical single-flight cache, and +receives them in the dispatch response's explicit-disclosure field. One envelope carries one +action, so quote (`read`) and buy (`execute`) are TWO grants on the same resource. No mandate, +no quote — there is no market-wide price oracle for free. + +One-command demo against a running runtime with a wired rail: +`elastos mandate market-demo [--amount N]` — provisions a cap, grants the two +single-asset mandates (read quote + execute pay) bound to one ephemeral agent key, has the agent +QUOTE the live terms and decide, dispatches the agent's signed buy, then revokes both mandates +and clears the cap — leaving the buy's ledger record for the panel to show. + +## The test seam (why CI needs no chain) + +The provider depends on two small traits — `DrmResolver` (resolve, fail-closed) and `DrmSettler` +(settle, two-generals). **CI injects mocks and exercises every branch**; production injects +`ChainDrmMarketplace`, which calls the real `resolve_token_id_live` + `buy_access`. **The live Base +path is this runbook — never a CI call.** + +## Live-chain smoke (operator runbook) + +On a box with the chain-provider configured for Base and a funded managed account: + +1. Export the env above with a real asset's KID as the payee and a listing you can afford. +2. Provision a cap covering the listing price: `POST /api/spend-budgets`. +3. Grant a bound pay-mandate to a test agent for `elastos://runtime/pay/` (Mandates app or + CLI), naming a responsible entity. +4. Dispatch a buy intent for the asset at the listing amount. +5. Confirm phase 1: the dispatch reports `authorized_not_performed`; `GET /api/payments/pending` + shows a `Pending` entry with the tx; the meter reservation is held; the receipt has NO rail_ref + yet. +6. Confirm phase 2: run the reconciliation once the tx reaches the confirmation floor — the entry + becomes `ResolvedCharged`, the receipt's pay-use row carries `rail_ref` with the real tx hash, + and the ERC-1155 ACCESS_TOKEN is owned by the buyer. (A reverted tx instead refunds the cap.) + +## Honest bounds (tracked as KNOWN_GAPS `MKT-DRM`) + +1. **Meter unit vs. on-chain price — CLOSED (Sprint 36).** The cap is now gated against the + on-chain price in the SAME unit via the declared `ELASTOS_DRM_SPEND_UNIT` mapping: a buy priced + above `amount × spend_unit` is refused before broadcast, and the buy binds the gated price as its + expected price (abort-on-drift). RESIDUAL: the mapping is operator-declared (the runtime does not + discover the pay-token's decimals on-chain) — a wrong declaration mis-scales the ceiling; a + deployment must set it to match the listing's pay-token. +2. **Confirmation depth — CLOSED (Sprint 35); unattended resolution — CLOSED (Sprint 37).** A + DRM buy is recorded `Pending` at broadcast and promoted to charged (with the receipt binding) + only after `reconcile_drm_confirmations` reads the tx mined + successful + at least + `ELASTOS_DRM_MIN_CONFIRMATIONS` deep; a reverted tx refunds. The in-runtime scheduler + (`ELASTOS_DRM_RECONCILE_INTERVAL_SECS`) now drives that poll unattended. RESIDUAL: the + scheduler is opt-in — a deployment that never sets the interval is back to the manual loop + (deliberate: no ambient background chain poller). +3. **Royalty splits** are the DRM protocol's invariant, not re-verified by Flint. diff --git a/docs/FLINT_MANDATE_ENGINE.md b/docs/FLINT_MANDATE_ENGINE.md new file mode 100644 index 00000000..bbdeda82 --- /dev/null +++ b/docs/FLINT_MANDATE_ENGINE.md @@ -0,0 +1,226 @@ +# Flint — The Mandate Engine + +**"Give your agent a mandate, not your keys."** + +Flint is the mandate/payment engine inside the ElastOS runtime: the layer that lets an operator +hand an AI agent a *scoped, expiring, revocable* mandate instead of raw credentials, have the +agent act under it unsupervised — including spending real money under a provable cap — and hold +the whole thing to a tamper-evident, off-box-verifiable record. This document is the reviewable +map; the detailed per-gap ledger lives in `KNOWN_GAPS.md`. + +**Vocabulary.** A *mandate* is a standing grant — a signed capability token plus its authorized +method envelope. The API calls it a standing grant (`/api/standing-grants/dispatch`), the audit +chain records it as `CapabilityGrant`/`CapabilityUse`, and the operator UI calls it a mandate; +all three name the same object. + +## The lifecycle, in one place + +| Verb | What it is | Where | +|---|---|---| +| **Grant** | Mint a real signed capability token scoped to (capsule, resource, action, ttl) + an authorized method set + the **responsible entity** (the DID the OPERATOR DECLARES accountable for the agent's acts — the EU-AI-Act liability *attribution*, signed into the grant record and the receipt; required on the shell app). **Operator-asserted, not attested:** the runtime records the DID verbatim; it does not resolve it or obtain the entity's counter-signature, so a receipt proves the operator's declaration, not the entity's consent (entity counter-signing is a tracked gap). | CLI + Mandates shell app | +| **Act** | An agent signs an `IntentDeclarationV1` and dispatches it; a fail-closed gate checks `intent ⊆ envelope` (capsule + agent-key + method + resource + action), runs a real executor, and reconciles declared-vs-done | `POST /api/agent/dispatch` (agent-facing, S26) or `/api/standing-grants/dispatch` (operator) | +| **Watch** | The operator sees mandates live, what each agent has written/delivered under them, and — for pay-mandates — the marketplace assets they scope (live on-chain quotes) and the buys as the ledger records them (pending always shown; settled ones windowed, stated) | Mandates shell app (mandate cards, Agent State panel, Inbox, Money + Marketplace panels) | +| **Revoke** | The kill switch — durably attested *before* the mandate dies | CLI + Mandates shell app | +| **Prove** | Export a portable `MandateReceipt` — proving not just WHAT the agent did but WHICH entity the operator DECLARED accountable (the responsible entity rides the signed grant record; operator-asserted, see Grant) — and verify it off-box with no runtime and no trust in this box. **Verifier version floor (S32):** a pre-S32 `verify-receipt` binary drops the new grant field on re-serialize and will false-flag an S32 receipt as tampered — verify with an S32+ binary. | `elastos verify-receipt` | + +## The real affordances behind dispatch + +An affordance is a genuine runtime operation an agent can invoke under a mandate. Each REPORTS what +it actually did; the receipt is minted from that report, never from the declaration, so an +authorized-but-unperformed act reconciles honestly (`authorized_not_performed`), never a fabricated +match (this is the G-M6 rule). + +| Method | Kind | Reports | Notes | +|---|---|---|---| +| `runtime.audit_verify` | read (side-effect-free) | `read` | Re-verifies the signed audit chain end to end; `performed` iff it truly verifies | +| `runtime.content_seen` | state-dependent read | `read` | Did THIS principal open a content id? Principal-scoped, no cross-principal oracle | +| `runtime.state_get` | attested VERIFY read | `read` | Verifies the acting principal's OWN durable state (the read pair of state_put); the agent declares the value it expects — `matched` attests "K = V", `diverged` means the guess was wrong (ONE BIT — the actual value is NOT returned or on-chain), `declined` if absent. Principal-scoped, exact-key, agent-key BOUND (F2) | +| `runtime.market_quote` | read (side-effect-free) | `read` | The agent SHOPS within its mandate (S39): quote the live on-chain terms of a granted asset (`elastos://runtime/pay/` — no market-wide oracle), through the ONE single-flight TTL-cached quote spine the Marketplace panel shares. One envelope carries ONE action, so quoting takes a `read` mandate on the same pay resource the `execute` pay-mandate scopes (two grants, one resource). Discovery mode (empty `input_hash`) performs and returns the terms via the response's explicit-disclosure channel; attested mode (declared terms) `Matched`-attests the terms AS OF THE SPINE'S LAST READ (≤30s old — a change inside the cache window is caught on the next re-read) and a changed listing reconciles `diverged`. A failed read declines honestly — `performed` only when terms truly returned (dev/chain-mock modes return synthetic free terms, as the panel also states) | +| `runtime.negotiate` | propose (non-value-moving) | `read` | The shop loop's MIDDLE leg (S50 — quote → **negotiate** → pay): the agent makes a bounded OFFER for a granted asset (same `elastos://runtime/pay/` scope), and the injected seller answers accept / counter / reject. THE PROVABLE PROPERTY: the offer rides the signed `input_hash` as a canonical positive integer of spend units, and an offer above the mandate's UN-SPENT cap (`SpendMeter::remaining`) is refused BEFORE it reaches the seller — an agent can never PROPOSE to commit its operator beyond granted authority. It only READS the cap (no reserve, no debit, no broadcast), so NO money moves here; settlement stays `runtime.pay`. Like `market_quote` it is a READ-authority probe (the dispatch gate authorizes only the fixed Action enum; the OFFER, not the action, makes it a proposal) — so it takes a `read` mandate on the same pay resource the `execute` pay-mandate scopes. Accept/counter `performed` echoing the offer (the receipt attests the bounded offer, NOT the counterparty's disposition, which the runtime cannot verify); the seller's terms ride the response's disclosure channel (ephemeral market data). Rejection declines honestly. Wired only where a rail has a listing to negotiate against (the DRM marketplace's fixed-price seller calls the SAME `authorize_amount_against_listing` the buy gate does — one shared spend-unit conversion + pay-token guard, so an accept corresponds exactly to what the buy will pass); unwired on HTTP/ERC-20 | +| `runtime.notify` | **side-effecting** | `message` | Delivers a message into the operator's Inbox; bounded fields, capped store, `performed` only after the write lands | +| `runtime.state_put` | **side-effecting** | `write` | Writes durable, readable-back, principal-scoped agent state; last-write-wins with attributed versioning | +| `runtime.pay` | **side-effecting, money** | `execute` | Spends real money to a mandate-scoped payee under a durable spend cap: the amount rides in the signed `input_hash`, over-cap or unprovisioned refuses with no money moved, and every outcome is classified two-generals-honestly. The full design — durability, rails, custody, reconciliation, the operator surfaces, and every honest bound — is in [The payment spine](#the-payment-spine-runtimepay) below | + +## The payment spine (runtime.pay) + +One pay spine, never a fork: whatever rail is wired, the meter, the ledger, the outcome +classification, and the signed receipt are byte-identical. + +### The cap is enforced, durable, and operator-provisioned + +- The spend meter reserves against the per-capsule cap ATOMICALLY before any money moves; over the + cap (or an unprovisioned capsule ⇒ zero) the payment is REFUSED with a signed + `authorized_not_performed` — no money moved (S27). +- The cap is DURABLE (snapshot + fsync; the reservation persists BEFORE money moves; a restart + never refills it; a corrupt or tampered-shape snapshot refuses to boot) and provisioned at + `POST /api/spend-budgets` or the Mandates Money panel. Each provision is attested on the signed + chain as a `ConfigChange` and rolled back if the attestation fails (S28). +- The meter POISONS on a post-publish persist failure (mutations refuse until reopened from disk; + memory never diverges from the visible snapshot) and holds a single-opener flock. + +### Outcomes are classified two-generals-honestly + +- **Charged** — the rail confirmed it; the spend stands and the rail reference is custodied. +- **Provably not charged** — refund the reservation. +- **Indeterminate** (timeout / 5xx / panic / broadcast-unconfirmed) — KEEP the reservation: + refunding against money that may have moved would break the cap, the one unbreakable invariant. + The decline reason names the idempotency key for rail-side reconciliation, and + `authorized_not_performed` here means NOT-ATTESTED, not proven-absent. + +### The rails (one trait, two implementations) + +- **HTTP rail (S29):** `ELASTOS_PAYMENT_ENDPOINT` (+ optional bearer `ELASTOS_PAYMENT_TOKEN`) + wires `HttpPaymentProvider` — a payment order (`payee`, `amount`, signature-derived + `Idempotency-Key`) POSTed to the deployment's payment service (a thin adapter fronts + Stripe/ACH/treasury/a crypto rail). HTTPS enforced (plaintext only to loopback), malformed + endpoints refuse at boot, redirects are never followed (a 3xx is indeterminate, never + "charged"). Requires the durable meter. The endpoint's obligations are the stated contract in + `docs/PAYMENT_ENDPOINT_CONTRACT.md`. +- **DRM marketplace rail (S34–S36):** `ELASTOS_PAYMENT_RAIL=drm` settles a buy ON-CHAIN via the + Elacity `buy_authority` path behind the SAME `PaymentProvider` trait — resolve (fail-closed on + ambiguity), read-only price quote, the price gate (`amount × ELASTOS_DRM_SPEND_UNIT` must cover + the on-chain price, quantity pinned to 1, pay-token declared and drift-armed), broadcast ⇒ + PENDING, and promotion to charged only after the tx is mined + successful + past the + confirmation-depth floor — driven unattended by the in-runtime confirmation scheduler when + `ELASTOS_DRM_RECONCILE_INTERVAL_SECS` is set (S37). The full rail — wiring, runbook, honest + bounds — is `docs/DRM_MARKETPLACE_RAIL.md`. +- The Mock rail stays dev/demo-gated behind `ELASTOS_ALLOW_MOCK_PAYMENTS` (a real endpoint wins if + both are set). + +### Custody and reconciliation (S30/S35) + +- The payment LEDGER durably custodies every rail attempt the process lived to record — the + performed payment's rail reference and a PENDING entry per indeterminate outcome (per-capsule + bounded, so one agent cannot blind a victim's obligations). Money-bearing keys are NEVER + evicted, and the durable ledger is the cross-window idempotency: a re-dispatched signed intent + whose key already moved-or-may-have-moved money is refused, never re-charged. +- Pending entries surface at `GET /api/payments/pending` and resolve EXACTLY ONCE at + `POST /api/payments/reconcile` (`charged=false` refunds, `charged=true` confirms; each + resolution attested on the signed chain). DRM pendings are additionally resolvable against the + chain itself via `reconcile_drm_confirmations` (see the DRM doc). + +### The operator surface and its authorization perimeter (S31/S33) + +- The Money panel (budgets with cap/spent/remaining/held-unconfirmed, the poisoned banner, the + reconciliation work list) is a read-only projection of the ONE enforcing meter+ledger + (`build_pay_rail`, same-Arc by construction, flock-enforced). +- The Marketplace panel (S38) is the same discipline pointed at the marketplace: the assets the + ACTIVE pay-mandates scope (with live on-chain quotes — TTL-cached and fan-out-bounded, so a + browser refresh storm is not a chain-read storm — one live read per asset per window, enforced + single-flight) and the buys as the ledger records them — every PENDING buy always (a flood of + new settled entries can never push a live obligation out of sight), the settled tail windowed + with the window stated — worded honestly (a broadcast is "awaiting chain confirmation", never a + purchase). STRICTLY read-only: + the panel has no buy verb — operators grant, agents act through the signed-intent dispatch. + One-command walkthrough: `elastos mandate market-demo ` (cap → pay-mandate → the + agent's signed buy → watch it resolve in the panel). +- Web provisioning is CEILING-BOUND server-side (`ELASTOS_WEB_MAX_SPEND_CAP`); verdict buttons are + arm→confirm; a not-charged verdict is refused while the meter is poisoned (it would burn the + one-shot refund handle). +- The mandates launch token is an HttpOnly, SameSite=Strict cookie path-scoped to the mandates API; + cookie-authorized writes require the anti-CSRF app-marker header; and every money write requires + a FRESH passkey verification (a WebAuthn ceremony ≤180s old, proof-bound to the same principal) + SPENT on exactly one applied write. + +### Honest bounds, stated + +- The cap is PER-CAPSULE, not per-mandate; an orphaned/indeterminate reservation over-counts the + cap fail-closed (recovery: rail-side lookup by idempotency key FIRST, then a deliberate cap + raise). +- A crash between the persisted reservation and the rail verdict leaves a durable reservation with + no ledger entry (recovered from the on-chain declaration); pending custody is + guaranteed-or-stated, terminal records best-effort. +- The 4xx⇒not-charged rule is a stated CONTRACT on the payment endpoint; a lying 2xx from a + compromised endpoint mints receipts the runtime cannot independently check — an HTTP-rail + Performed pay is a RAIL-TRUST attestation, weaker than the runtime-verified affordances. (A DRM + buy is stronger: it is chain-CONFIRMED before it is charged.) +- The spent-passkey guard is in-memory (a gateway restart inside the ~3-minute window could admit + one replay), and a runtime with no passkey enrolled makes money writes CLI-only — both tracked + as G-M9. +- The snapshot files are trusted from `data_dir` (not self-authenticating, unlike the signed + chain); the flock/parent-fsync protections are unix-only. Every provider subprocess a + money/access path traverses (chain, wallet-sign, rights-decide) AND every access-path content + sidecar (the media/object authorities and the grant sidecar, S42) is deadline-bounded (S40–S42, + one shared watchdog) — no runtime thread parks forever on a hung or hostile provider, and the + bounded reap leaves no zombie; the kill is unix-only. +- DRM-rail residuals are tracked as `MKT-DRM` in `KNOWN_GAPS.md` (the operator-declared spend-unit + mapping; the confirmation scheduler being opt-in — unset interval ⇒ back to the manual + reconcile loop). + +## The trust model (and its honest caveats) + +- **The runtime is the single audit writer.** Trust in a receipt derives from a signed `did:key` + pinned out-of-band; verification is fully off-box (`elastos verify-receipt --signer`). +- **The shell is the grant root (G-M3).** Issuing/revoking authority lives behind the shell's + consent-broker gate (API) and the app-bound home-launch token (gateway) — the same trust tier. A + compromised shell can already mint anything, so shell-held mandate power is *contained*, not new. +- **Agent-key binding is optional today (G-M4).** A mandate MAY bind one agent's ed25519 key + (strong attribution); unbound, it is capsule-string-only. Promoting binding to default is tracked. +- **Same-disk / same-host caveats, stated not hidden:** durable stores are fail-closed on corrupt + boot but not defended against a root attacker who already owns the key material; the replay guard's + freshness window trusts the host clock (fail-closed both directions — see below). + +## Gaps closed vs open (mandate track) + +**Closed:** G-M1 (liveness consults every kill path), G-M2 (token-keyed `CapabilityUse` in the +receipt), G-M5 (durable registry + replay guard survive restart and power loss), G-M6 (the +reconciliation seam — receipts minted from what executors report). + +**Agent-facing dispatch shipped (S26):** the ACT leg is now reachable by the AGENT itself at +`/api/agent/dispatch` — not only the operator shell. The agent authenticates AS the mandate holder +(the signed intent proves key possession; the mandate's agent-key binding proves authorization), so +NO operator session/keys are needed — the literal "a mandate, not your keys". The route requires a +BOUND mandate (no ambient authority), refuses a wrong-key/unbound/absent mandate with a uniform 403, +and checks the binding BEFORE the rate budget (charge-on-authorized — a wrong-key flood can't lock +out a victim). The operator shell route remains for operator-driven dispatch and unbound mandates. + +**Open / tracked (by design or roadmap):** +- **G-M3** — shell is the grant root (accepted trust model). +- **G-M4** — agent-key binding optional; REQUIRED on the agent-facing dispatch route + for state_get + mandates. Promoting binding to the universal default (every side-effecting/state affordance) is the + tracked endpoint. +- **G-M7** — operational hardening. *Paid down:* the replay guard is time-windowed + bounded + + clock-attack-hardened (S19); dispatch is rate-budgeted + grant-existence-gated (S21) with a + per-mandate configurable budget (S22); and the working registry's DEAD accumulation is now bounded + on both axes — time-retention + hard cap that never sheds a live mandate (S23). Durable *dead* + state (replay set, dispatch rate, dead grants) is bounded; *live* mandate growth stays real + operator authority by design (never shed). Mandate mint is now FAIL-CLOSED (S24): `grant_durable` + emits the signed `CapabilityGrant` before returning the token, so a mandate whose grant cannot be + recorded is never issued — the receipt is a complete record of every issued mandate's GRANT and act + DECLARATION (reconciliation verdicts remain best-effort — the disclosed executor-report seam). This + holds as durably as the audit log's backing: fully under the file-backed EU-AI-Act mode, in-process + under the default memory-only log (the same bound as the fail-closed revoke). *Remaining:* + a request-RATE limiter on the gateway mint/revoke routes; and the principled fix for one-click + broad grants is role-based capability tiering (a `CapsuleRole::System`), a separate initiative + deliberately NOT wedged in on a spoofable capsule name. + +## The replay guard (security core) + +Each signed intent acts at most once. The guard is **durable** (survives restart/power loss), +**time-windowed** (a captured declaration expires after `MAX_INTENT_AGE_SECS`; future-dated ones are +refused), **bounded** (the seen-set self-compacts against the retention window instead of growing +forever), and **clock-attack-hardened** (a persisted, monotonic anti-readmit watermark refuses any +intent at/below the highest evicted `declared_at`, so a backward clock step cannot readmit a +compacted id — under any clock, across restart). `RETENTION = age + skew` is the load-bearing margin. + +## Review discipline + +Every increment ran the same standard before commit: gate (build + clippy + full test suites), +then two independent adversarial reviews (a principles guardian and a red team), then every +finding folded with a ratchet test that reproduces the exact failure — nothing dismissed as noise. + +## Verification status + +- `cargo clippy` clean across `elastos-runtime`, `elastos-server`, `elastos-common`; test suites + green (run `cd elastos && cargo test --workspace`, or `just test`). +- No `todo!()`/`unimplemented!()` in the mandate path; every closed gap carries a ratchet, every open + gap a documented reason. + +## What a reviewer should look at first + +1. `elastos-runtime/src/capability/intent.rs` — the gate, the standing-grant store, the replay guard. +2. `elastos-server/src/intent_executor.rs` — the affordances (including `runtime.pay`) + the reconciliation seam. +3. `elastos-server/src/api/handlers/capability.rs` — issue/revoke/dispatch handlers + receipt export. +4. `elastos-server/src/api/gateway_mandates.rs` — the shell app's read/grant/revoke surface. +5. `capsules/mandates/index.html` — the operator UI (list, receipt drawer, grant form, kill switch, Agent State). +6. `docs/KNOWN_GAPS.md` — the honest ledger of every gap, closed and open. diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md index d2fc9089..b69f7063 100644 --- a/docs/GLOSSARY.md +++ b/docs/GLOSSARY.md @@ -203,3 +203,45 @@ remain provider authority, while Library/Home show the mounted WebSpace view. Mutable WebSpace mounts/forks can also materialize local provider-owned objects with explicit access-policy metadata; that local materialization is provider state, not a raw app-visible filesystem alias. + +## Flint + +The mandate/payment engine inside the ElastOS runtime — "give your agent a mandate, not your +keys." Entry point: [FLINT_MANDATE_ENGINE.md](FLINT_MANDATE_ENGINE.md). + +## Mandate (Standing Grant) + +Scoped, expiring, revocable authority an operator grants an AI agent: a signed capability token +plus an authorized method envelope (and optionally a bound agent key). "Mandate" is the product +noun; the API says "standing grant"; the audit chain records `CapabilityGrant`/`CapabilityUse`. +All three are the same object. + +## Responsible Entity + +The DID the operator DECLARES accountable for every act under a mandate, recorded verbatim on the +signed grant record and carried into the receipt. Operator-asserted, not attested — it proves the +operator's declaration, not the entity's consent. + +## Mandate Receipt + +A portable, self-contained export of a mandate's signed audit records (grant, acts, revocation), +verifiable off-box with `elastos verify-receipt` — no runtime, no trust in the exporting box. + +## Spend Unit + +The abstract unit the spend meter caps in. On the DRM rail, `ELASTOS_DRM_SPEND_UNIT` declares how +many pay-token smallest-units one spend unit equals, making the cap a literal on-chain ceiling. + +## Rail / rail_ref + +A payment rail is a `PaymentProvider` implementation (HTTPS adapter, DRM marketplace, dev mock). +`rail_ref` is the rail's settlement reference — for a DRM buy, +`drm:tx=;op=;tid=;price=;tok=` — bound onto the signed +`CapabilityUse` (and thus the receipt) once the settlement is CONFIRMED. + +## Pending / Indeterminate (payments) + +A rail outcome is *indeterminate* when the charge may or may not have posted (timeout, 5xx, +broadcast-not-yet-confirmed); the reservation is KEPT and a *Pending* ledger entry custodies the +obligation until it is resolved exactly once (refund or confirm). Fail-closed: money that may have +moved is never refunded against. diff --git a/docs/INVESTOR_ONE_PAGER.md b/docs/INVESTOR_ONE_PAGER.md new file mode 100644 index 00000000..1f1618d9 --- /dev/null +++ b/docs/INVESTOR_ONE_PAGER.md @@ -0,0 +1,60 @@ +# Elacity — One Pager + +## The one line +**The runtime for selling anything digital — including AI models and data — where +the buyer can use it but never gets the file, the key, or the weights.** + +## The problem +Two things the AI era needs and today's stack cannot provide: +1. **Enforced authority, not logs.** As agents act on our behalf, "we logged that + the agent did X" is not enough — you need to *prevent* what a fooled agent + shouldn't do, and *prove* what it was allowed to touch. +2. **Sell AI models & data without giving them away.** A model owner who ships + weights has lost them. There is no clean way to monetize a model, a dataset, or + a likeness while keeping control. + +## What we built +A **capability-security kernel + decentralized post-quantum DRM**: +- **Encrypt once, mint rights on-chain.** Any file becomes a tradeable access + token on Base with creator-set price, royalties, and resale rules. +- **Open inside a containment boundary.** Ten viewers across five tiers ship + today; the buyer sees pixels/frames, never the bytes or the key. +- **No single party holds the key.** A 2-of-3 threshold key-management quorum + (real distributed key generation) releases keys only against an on-chain + entitlement — post-quantum (ML-KEM-768 + ML-DSA-65) at the core. +- **Tamper-evident receipts.** A hash-chained, signed audit trail proves the + custody chain — the kind of record a regulator or insurer can rely on. + +## The moat +The defensible intersection — **runtime execute-containment × on-chain rights × +threshold key custody** — lets us do the one thing incumbent DRM structurally +cannot: **sell a runnable model or game that executes for the buyer while the +binary and weights never leave the sandbox.** That is not a feature bolted on; it +*is* the capsule architecture. + +## How it makes money +- **Marketplace fee** on every primary sale (protocol cut, read live on-chain). +- **Resale royalties** — the protocol re-clips a cut on every secondary trade; + creators earn a recurring reseller royalty. +- **Key-release toll** — every open requires a quorum key release: a meterable + per-open / subscription line. +- **AI-model & data licensing (the wedge)** — decrypt-to-inference and + training-rights licensing of models, datasets, likeness and voice, with + on-chain royalties. + +## Where we are (honest) +- **Security & cryptography audit-grade** (8/10 both): fail-closed capability + enforcement and a post-quantum threshold-DRM core, independently reviewed. +- **Marketplace built end-to-end** against live Base contracts (buy / list / + resell / royalties). +- **Pre-revenue on the new stack**, by discipline — we publish no vanity metrics. +- **Next milestones:** first public receipt-backed sale, and the flagship Tier-3 + "runnable model, weights never leave" demo. + +## The ask +Fund the two milestones that convert audited technology into a category: +one credible, on-chain, receipt-backed sale — and the Tier-3 demo that only the +capsule model can deliver. + +*(Internal note: technical diligence should read `docs/AUDIT_2026-07-03.md` for +the honest grade card, the trust-boundary caveats, and the roadmap.)* diff --git a/docs/KNOWN_GAPS.md b/docs/KNOWN_GAPS.md index 7a303475..c5adbbcd 100644 --- a/docs/KNOWN_GAPS.md +++ b/docs/KNOWN_GAPS.md @@ -1,6 +1,8 @@ -# KNOWN_GAPS — Capsule Inspector +# KNOWN_GAPS — the build-visible gap registry (runtime-wide) -Build-visible registry of what the Inspector does **not** yet assert, so gaps are +Build-visible registry of what the runtime does **not** yet assert — it began with the Capsule +Inspector and now ledgers gaps across the whole runtime (Inspector, Flint mandate/payment engine +`G-M*`/`MKT-*`, carrier, audit, egress) — so gaps are impossible to forget and "we should fix this" becomes a tracked, enforceable contract instead of prose. (Pattern from `LESSONS.md`: *turn an audit into a build-visible gap registry, not a doc that rots*.) @@ -20,7 +22,7 @@ green, and the row moves to "Closed." | # | Gap | Why open | Ratchet test (`#[ignore]`d) | Close criteria | |---|-----|----------|------------------------------|----------------| -| MKT-1 | **(High — on-chain-reachable) KID→ledger-tokenId resolver can confidently mis-bind to a hostile token** | Red-team 2026-07-03 (CONFIRMED, pre-existing in `feat/marketplace-runtime`, transplanted byte-identical in slice 1). `capsules/chain-provider/src/abi.rs:409` "prefer precise over substring" + the resolve loop's newest-first, creator-unconstrained window scan (`src/main.rs`) defeat the headline "fail-closed on ambiguous binding": (i) a legit asset minted via a RELAYER (the common case on Base) decodes into `substring` while a hostile canonical mint whose `opRawData` starts with the victim's public 16-byte KID lands in `precise`, so `precise` wins and the buyer binds the attacker's `(operative, tokenId)`; (ii) uniqueness is only evaluated WITHIN one 10 000-block window, so a hostile mint in a newer window is returned before the victim's older window is scanned. The KID is public (readable from the victim's own mint calldata). The buy binds — and pays for — the attacker's token. NOT client-API-reachable (the `chain` proxy allowlist excludes `resolve_token_id`), but the adversary here is the chain itself (any co-channel minter). | *Pending* — the ratchet would assert: given a victim mint + a hostile canonical mint carrying the victim's KID prefix, in the same AND in a newer window, `resolve_token_id` returns `None` (fail-closed), never the attacker's token. | Resolver binds a KID→tokenId ONLY when the candidate is creator-authenticated (constrain the scan to the asset's own channel/creator) or fails closed across ALL windows on any cross-tier/cross-window ambiguity; ratchet green. Fix before the marketplace goes live. | +| MKT-1 | **(High — on-chain-reachable) KID→ledger-tokenId resolver mis-bind — CLOSED (fail-closed global uniqueness)** | Red-team 2026-07-03 (CONFIRMED, pre-existing in `feat/marketplace-runtime`, transplanted byte-identical in slice 1). The old `abi.rs` "prefer precise over substring" + newest-first, return-on-first-window scan (`src/main.rs`) defeated the headline "fail-closed on ambiguous binding": (i) a legit asset minted via a RELAYER decoded into `substring` while a hostile canonical mint carrying the victim's public 16-byte KID landed in `precise`, so `precise` won and the buyer bound the attacker's `(operative, tokenId)`; (ii) uniqueness was only evaluated WITHIN one window, so a hostile mint in a newer window was returned before the victim's older window was scanned. **CLOSED 2026-07-03**: `pick_asset_created_binding_kid` → `collect_kid_bindings` now returns the UNION of both bind methods (no precise-over-substring preference — kills (i)), and `resolve_token_id` accumulates every distinct `(operative, tokenId)` across the WHOLE channel range (never returns on the first window — kills (ii)) and binds ONLY when exactly one exists, else returns `ambiguous_kid_binding` (buy blocked). This trades availability (a griefer can block a resolve by minting a same-channel KID collision) for safety (funds are never bound to the wrong token) — the correct money-path default. The channel-topic filter bounds the scan; an early-exit on ≥2 distinct binders caps the ambiguous/griefing path. | Enforced by `abi::tests::collect_kid_bindings_binds_the_unique_asset` (unique binds), `..._surfaces_both_binders_in_one_window_so_caller_fails_closed` (same-window ambiguity), and `kid_bindings_across_windows_fail_closed_on_cross_window_collision` (cross-window). | **CLOSED.** Residual (lower priority): creator-constraining the scan (topic[1] is null today) would let a legit asset still RESOLVE under griefing instead of failing closed — a future availability hardening, not a funds risk. | | MKT-2 | **(hardening) Resolve path has no aggregate RPC time/size budget** | Red-team 2026-07-03 (pre-existing, transplanted). `capsules/chain-provider/src/main.rs` fetches one `eth_getTransactionByHash` per `AssetCreated` log across every window from `latest` down to `deploy_block` with no cap on total calls / wall-clock; a caller-supplied lower `from_block` deepens it and a mint-spammed channel amplifies per-window fan-out. Each call is individually bounded (15 s) but the aggregate is not. Internal buy path only (not client-reachable), so DoS-class, not an external primitive. | *Pending* (resource bound, not a unit ratchet). | An absolute per-resolve budget (max windows / max tx fetches / wall-clock deadline) that fails closed when exceeded. | | MKT-3 | **(hardening) media-provider writes the caller-supplied `progress_path` with no confinement** | Red-team 2026-07-03 (pre-existing in the ddrm original + restored in `451faab`). `capsules/media-provider/src/main.rs:994` `write_transcode_progress` writes `{path}` + `{path}.tmp` raw from the request field — an arbitrary file create/truncate primitive for any caller who reaches `package_dash`, contradicting the module's "confined to the scratch dir" doc. Capped today: `media` is NOT in the client-facing proxy allowlist and the host generates the sink path with a process/clock/counter nonce (`creator.rs::pkg_progress_sink_path`, never from client input) — so it is a missing second line of defense, not exploitable via the shipped surface. | *Pending* — assert the provider REJECTS a `progress_path` that is not absolute + under the configured scratch dir. | The provider validates `progress_path` (`is_absolute` + canonicalize + `starts_with(scratch)`) and refuses otherwise; ratchet green. | | MKT-4 | **(hardening) `run_ffmpeg_with_progress` can wedge if the stdout `-progress` pipe read errors mid-encode** | Red-team 2026-07-03 (pre-existing, restored in `451faab`). `capsules/media-provider/src/main.rs:950` breaks the stdout loop on a read error and then `child.wait()`s with the pipe undrained; if ffmpeg keeps emitting progress it can block on a full pipe and `wait()` never returns (the stderr side-thread keeps draining, so only stdout wedges). Low probability (the normal path is ffmpeg closing stdout on exit); no zombie (wait is always reached on the happy path). Secondary: stderr accrues into an unbounded `String`. | *Pending* — a fault-injection test that errors the stdout read mid-stream and asserts the call returns within a deadline. | On an early stdout-loop exit, kill/await the child with a deadline (never an unbounded `wait()`); bound the stderr capture. | @@ -32,7 +34,7 @@ green, and the row moves to "Closed." | AUD-6 | **(Low)** Boot-critical sub-provider registration failure is warn-swallowed | `server_infra.rs` registers ~22 sub-providers at boot; on a `register_sub_provider` `Err` it logs `tracing::warn!` and continues (`:167,:199,:303,…,:1009`). The capability still fails closed at route time (`NoProvider`), so this is not fail-OPEN in the data sense — but a boot-critical provider that SPAWNED yet failed to register (e.g. a future merge drops its name from `RESERVED_SUB_NAMES`) leaves the mint/escrow path silently dark with only a warn to catch it. Distinguish absent-binary (genuinely optional → warn ok) from spawned-but-registration-rejected (an invariant violation → should be loud). The manifest-scan test `test_all_capsule_provided_sub_schemes_are_reserved` now catches the specific name-drop cause pre-boot; AUD-6 is the residual boot-time posture. Related: the pinned first-writer-wins guard (`8b688fc`) already makes a boot-critical overwrite a structural `Err`. | `#[ignore]`d `server_infra::tests::aud6_boot_critical_sub_provider_registration_fails_loud` — scans for the warn-swallow line per boot-critical scheme; fails today listing the ones still swallowing. **PARTIAL**: `encrypt` (CEK escrow) is rewired to propagate its registration failure (`?`, fails boot loud — smoke-validated); the ratchet stays ignored until publish/media/key/decrypt/drm/rights/wallet/chain follow (each needs the critical-vs-optional confirmation). | Boot fails loud when a boot-critical provider spawns but cannot register; absent-binary stays a warn; ratchet green. | | G1b | Observed grants not LIVE in the serve inspector (capsule_id correlation) | The granted-caps projection + source are proven (see Enforced invariants), but the only production `capability_grant` recorder (`grant_request`) keys `capsule_id` to the **session UUID** (an explicit "session ID as capsule ID for now" shim at `api/handlers/capability.rs`), while the inspector keys `granted_for_capsule` by the capsule **manifest name** — so wiring `RuntimeAuditLogGrantSource` onto the serve inspector would fold UUID-vs-name and ALWAYS show empty (verified by the loop-8 swarm + adversary). Not wired, to avoid a misleading always-empty surface. **UPDATE (flip `cbc8929e`): the correlation is now FIXED** — grants record under the canonical `vm-{name}` and the inspector folds the same key (ratchet green). The REMAINING G1b gap is purely serve WIRING: the live serve path attaches only `AuthAuditSource` (no grant source), so `granted_for_capsule` returns the default empty Vec. | **DONE `21a72b49`** (see Enforced invariants). | **G1b CLOSED `21a72b49`** — `CompositeAuditSource` wired on both serve inspector sites over `capability_manager.audit_log()` (the same Arc `grant()` records to); a running capsule's observed grants now surface on the live inspect path. | | G-ID | No canonical capsule identity — the five-beat loop holds in TEST only, not prod (root cause of G1b) | Verified by the identity swarm + 3 adversaries (unanimous **decision-needed**): there are **≥5 distinct** capsule/vm/session id strings, and the THREE production consumers of a token's `capsule_id` each expect a DIFFERENT one — the HTTP plane validates `token.capsule == session.id` (random UUID, `storage.rs:453`/`namespace.rs:82`/`provider.rs:121`); the microVM carrier gate validates `== "vm-{name}"` (`supervisor.rs:1099` → `manager.rs:310`); the inspector folds grants keyed by the **bare manifest name** (`inspect_provider.rs:784`, == G1b). No single value satisfies all three. The honest lever (`session.vm_id`) is **None for every prod capsule session** (`create_session(SessionType::Capsule, None)`, `supervisor.rs:1004/1190`). The proven five-beat e2e runs only because the test binds `capsule_id` to its session; it does NOT exercise prod. (WASM carrier `runtime.rs:105` is a separate 4th identity domain; `vm-{name}` is NOT instance-unique — the unique handle is `vm-{name}-{cid}-{millis}`.) | **Founder ratified `vm-{name}` + interim-first (2026-06-25). INTERIM DONE `938013a9`**: capsule sessions now carry the real `vm-{name}` (`session.vm_id`, populated at the supervisor mint sites), and the requester's identity is recorded on the pending request (`requester_capsule_id`) on BOTH the HTTP and carrier paths — honest `None` when absent, NO validate gate changed. | **FLIP DONE `cbc8929e` — G-ID CLOSED** (see Enforced invariants): the mint keys the token on `requester_capsule_id` (fail-closed FORBIDDEN on `None`), the 3 HTTP gates re-keyed to `session.vm_id` atomically, the live viewer regression fixed (`serve_web_capsule` app_session populated with `vm-{name}`), and the inspector normalized — the loop holds in PROD. Residual (NOT G-ID): G1b-LIVE granted-caps still needs a CompositeAuditSource on serve (see G1b); WASM-carrier identity (`runtime.rs:105`) + the print-only/operator None-vm_id Capsule sites (`orchestrator.rs:39`, `serve_cmd.rs:345`) stay intentional fail-closed follow-ups. **UPDATE `279dac1`: `attach.rs` is no longer among these** — attach-authenticated host sessions now carry an honest `host-shell`/`host-client` identity (the attach secret is owner-only), so capability grant + token redemption work over the managed-home flow (`elastos home`); this closed a live-only fail-closed dead-end the smoke caught (was silently hanging on "Capability request still pending"). | -| G8 | Audit sink not fully signed+durable+fail-closed for the capability auth plane | Post-merge, Plane A (`primitives::audit::AuditLog`) is now dDRM's SIGNED, durable, tamper-evident hash chain (per-record ed25519 + `verify_chain`, durable-before-advance, fail-closed `emit`) — the canonical signed+durable plane G8 sought; the user-deny (G8a) rides it fail-closed. Plane B (`RuntimeAuditEventV1`) is signed+durable, carries auth/session events and its signature is produced and now VERIFIABLE (`crypto::domain_separated_verify` added + round-trip enforced) but no READ path verifies it yet, and capability events are not on Plane B. G8a (user-deny fail-closed-on-write) and the verifier primitive (G8b step 1) are DONE — see Enforced invariants. | *Pending scaffold (G8b)*: a `CapabilityDenied` routed through Plane B persists with a signature a new `domain_separated_verify` accepts under the runtime DID key (a real sign->verify round-trip, not `signature.is_some()`). | One canonical signed+durable plane carries capability deny/grant/use/revoke; signature verified on read. (G8a done.) **REVOKE NOW FAIL-CLOSED `W3b-turn` (G8b slice):** `CapabilityManager::revoke` (the token-level revoke behind the 3 prod callers — revoke-by-shell, revoke-via-inspector, revoke-by-user-API) was fail-OPEN (mutate-then-best-effort-emit); now it emits the signed durable `CapabilityRevoke` BEFORE killing the token and returns `Result` — on an audit-write failure the revoke ABORTS (token stays valid) and the 3 callers surface it (500/error), mirroring AUD-3's `revoke_request`. Proven by `capability::manager::tests::revoke_fails_closed_when_audit_write_fails` (read-only-fd seam: revoke errs + token still validates). So deny/approve/revoke (request- AND token-level) + affordance-use are now all fail-closed-signed. **STILL OPEN (the two hard halves):** (1) **verify-on-read** is now AVAILABLE opt-in `W3b-turn` (no longer fully blocked): `AuditLog::with_file_verified` opens a file-backed log AND walks the existing hash+signature chain, returning `Err` (so server startup ABORTS fail-closed) if any on-disk record fails — you can never append a fresh valid-looking tail onto a tampered history. `server_infra` opts in via `ELASTOS_AUDIT_LOG_PATH` (the EU AI Act durable-custody mode); the DEFAULT stays memory-only `AuditLog::new()` so the per-validate hot path keeps NO fsync until the group-commit rewrite (below). Proven by `primitives::audit::tests::with_file_verified_resumes_clean_log_and_rejects_tamper`. **TAIL-TRUNCATION NOW CLOSED `W3b-turn`:** every durable `emit` persists the committed head seq to a `.head-anchor` sibling (atomic temp+rename, under the chain lock, best-effort so it never lies low), and `with_file_verified` refuses to open when fewer records verify than the anchor committed — so records sliced off the END (which the chain walk alone can't see) are now caught fail-closed. Proven by `primitives::audit::tests::with_file_verified_detects_tail_truncation`. RESIDUAL: the anchor is an unsigned same-disk host file — it defends against truncation that does NOT also rewrite the anchor (rotation bugs, partial tamper, naive `truncate`); a full-disk attacker rewriting BOTH needs an off-box/co-signed anchor (roadmap, same custody caveat as the signing key). **LIVE READ PATH NOW LANDED `W3b-turn`:** `AuditLog::chain_attestation()` runs the full hash+signature `verify_chain` walk under the log's own key and returns a serializable `ChainAttestation {verified, records, signer, error}`; the capsule inspector projects it as `audit.chain` (via `AuditSource::chain_attestation` → `RuntimeAuditLogGrantSource` over the runtime AuditLog), so a LIVE inspect (not just startup) re-verifies the whole chain — catching reorder/drop/tamper mid-session, beyond the per-event AUD-4 signature checks. `null` for a memory-only plane (no durable chain to attest, never a fabricated ok). Proven by `audit::tests::chain_attestation_reports_live_integrity_and_catches_tamper` + `inspect_provider::tests::capsule_detail_projects_live_chain_attestation`. **W7 EXPORT NOW SELF-VERIFYING `W3b-turn`:** the EU-AI-Act artifact (`ai_act_audit.ts`) embeds an optional `ChainAttestation` (mirror of the Rust serde struct) in `record_keeping.chain_attestation`, and `containmentEvidence` fails **Art 12 fail-closed** when a PRESENT chain did not verify (a tampered custody chain cannot back the tamper-evident record); an absent attestation falls back to the signed-record check (back-compatible). So a consumer of the exported artifact sees the live chain result (`verified`, `records`, `signer`), not just a claim. Proven by the +3 node:tests (29 total, tsc strict). **RUNTIME READ PATH NOW LANDED `W3b-turn`:** the inspector exposes a System-scope `audit_attestation` op that returns the LIVE global `ChainAttestation` (`{verified, records, signer, error}`) for an exporter to fetch and pass to the TS `toAiActAuditRecord(consent, receipt, chain)` — both halves of the export wire now exist and align by the shared serde shape (Rust `chain_attestation` ⇄ TS `ChainAttestation`). Proven by `inspect_provider::tests::audit_attestation_op_returns_live_global_chain_for_export` (clean ⇒ verified; on-disk tamper ⇒ verified=false; memory-only/no-source ⇒ null). RESIDUAL: the end-to-end EXPORT ORCHESTRATION (a tool that calls the op, gathers receipts + consent, and emits the artifact) is out-of-repo — `toAiActAuditRecord` has no in-repo prod caller; and the serve inspector only carries the grant/chain source under durable mode. (2) **ordinary grant/use** stay best-effort by design (the per-validate hot path — making them fail-closed-signed adds an fsync per validate; needs the audit group-commit rewrite first, MEASURE-first/KVM lane). NOTE: a swarm proposed a parallel domain-separated signature for CapabilityApproved — REJECTED as redundant (Plane A already per-record ed25519-signs every event). | +| G8 | Audit sink not fully signed+durable+fail-closed for the capability auth plane | Post-merge, Plane A (`primitives::audit::AuditLog`) is now dDRM's SIGNED, durable, tamper-evident hash chain (per-record ed25519 + `verify_chain`, durable-before-advance, fail-closed `emit`) — the canonical signed+durable plane G8 sought; the user-deny (G8a) rides it fail-closed. Plane B (`RuntimeAuditEventV1`) is signed+durable, carries auth/session events and its signature is produced and now VERIFIABLE (`crypto::domain_separated_verify` added + round-trip enforced) but no READ path verifies it yet, and capability events are not on Plane B. G8a (user-deny fail-closed-on-write) and the verifier primitive (G8b step 1) are DONE — see Enforced invariants. | *Pending scaffold (G8b)*: a `CapabilityDenied` routed through Plane B persists with a signature a new `domain_separated_verify` accepts under the runtime DID key (a real sign->verify round-trip, not `signature.is_some()`). | One canonical signed+durable plane carries capability deny/grant/use/revoke; signature verified on read. (G8a done.) **REVOKE NOW FAIL-CLOSED `W3b-turn` (G8b slice):** `CapabilityManager::revoke` (the token-level revoke behind the 3 prod callers — revoke-by-shell, revoke-via-inspector, revoke-by-user-API) was fail-OPEN (mutate-then-best-effort-emit); now it emits the signed durable `CapabilityRevoke` BEFORE killing the token and returns `Result` — on an audit-write failure the revoke ABORTS (token stays valid) and the 3 callers surface it (500/error), mirroring AUD-3's `revoke_request`. Proven by `capability::manager::tests::revoke_fails_closed_when_audit_write_fails` (read-only-fd seam: revoke errs + token still validates). So deny/approve/revoke (request- AND token-level) + affordance-use are now all fail-closed-signed. **STILL OPEN (the two hard halves):** (1) **verify-on-read** is now AVAILABLE opt-in `W3b-turn` (no longer fully blocked): `AuditLog::with_file_verified` opens a file-backed log AND walks the existing hash+signature chain, returning `Err` (so server startup ABORTS fail-closed) if any on-disk record fails — you can never append a fresh valid-looking tail onto a tampered history. `server_infra` opts in via `ELASTOS_AUDIT_LOG_PATH` (the EU AI Act durable-custody mode); the DEFAULT stays memory-only `AuditLog::new()` so the per-validate hot path keeps NO fsync until the group-commit rewrite (below). Proven by `primitives::audit::tests::with_file_verified_resumes_clean_log_and_rejects_tamper`. **TAIL-TRUNCATION NOW CLOSED `W3b-turn`:** every durable `emit` persists the committed head seq to a `.head-anchor` sibling (atomic temp+rename, under the chain lock, best-effort so it never lies low), and `with_file_verified` refuses to open when fewer records verify than the anchor committed — so records sliced off the END (which the chain walk alone can't see) are now caught fail-closed. Proven by `primitives::audit::tests::with_file_verified_detects_tail_truncation`. RESIDUAL: the anchor is an unsigned same-disk host file — it defends against truncation that does NOT also rewrite the anchor (rotation bugs, partial tamper, naive `truncate`); a full-disk attacker rewriting BOTH needs an off-box/co-signed anchor (roadmap, same custody caveat as the signing key). **LIVE READ PATH NOW LANDED `W3b-turn`:** `AuditLog::chain_attestation()` runs the full hash+signature `verify_chain` walk under the log's own key and returns a serializable `ChainAttestation {verified, records, signer, error}`; the capsule inspector projects it as `audit.chain` (via `AuditSource::chain_attestation` → `RuntimeAuditLogGrantSource` over the runtime AuditLog), so a LIVE inspect (not just startup) re-verifies the whole chain — catching reorder/drop/tamper mid-session, beyond the per-event AUD-4 signature checks. `null` for a memory-only plane (no durable chain to attest, never a fabricated ok). Proven by `audit::tests::chain_attestation_reports_live_integrity_and_catches_tamper` + `inspect_provider::tests::capsule_detail_projects_live_chain_attestation`. **W7 EXPORT NOW SELF-VERIFYING `W3b-turn`:** the EU-AI-Act artifact (`ai_act_audit.ts`) embeds an optional `ChainAttestation` (mirror of the Rust serde struct) in `record_keeping.chain_attestation`, and `containmentEvidence` fails **Art 12 fail-closed** when a PRESENT chain did not verify (a tampered custody chain cannot back the tamper-evident record); an absent attestation falls back to the signed-record check (back-compatible). So a consumer of the exported artifact sees the live chain result (`verified`, `records`, `signer`), not just a claim. Proven by the +3 node:tests (29 total, tsc strict). **RUNTIME READ PATH NOW LANDED `W3b-turn`:** the inspector exposes a System-scope `audit_attestation` op that returns the LIVE global `ChainAttestation` (`{verified, records, signer, error}`) for an exporter to fetch and pass to the TS `toAiActAuditRecord(consent, receipt, chain)` — both halves of the export wire now exist and align by the shared serde shape (Rust `chain_attestation` ⇄ TS `ChainAttestation`). Proven by `inspect_provider::tests::audit_attestation_op_returns_live_global_chain_for_export` (clean ⇒ verified; on-disk tamper ⇒ verified=false; memory-only/no-source ⇒ null). RESIDUAL: the end-to-end EXPORT ORCHESTRATION (a tool that calls the op, gathers receipts + consent, and emits the artifact) is out-of-repo — `toAiActAuditRecord` has no in-repo prod caller; and the serve inspector only carries the grant/chain source under durable mode. (2) **ordinary grant/use** stay best-effort by design (the per-validate hot path — making them fail-closed-signed adds an fsync per validate; the group-commit PREREQUISITE LANDED `S51` (concurrent emits now share fsyncs — measured 2.9× at 8 threads, contract unchanged), so the remaining cost of fail-closed grant/use is ~1 fsync of LATENCY per validate (not a throughput collapse); flipping them fail-closed is now a POLICY decision to take deliberately, not a blocked one). NOTE: a swarm proposed a parallel domain-separated signature for CapabilityApproved — REJECTED as redundant (Plane A already per-record ed25519-signs every event). | | G1b | Granted capabilities not wired into the **serve** path | The product inspector now lists OBSERVED grants via `RuntimeAuditLogGrantSource` over the in-memory `AuditLog` (the plane carrying resource+action), proven end-to-end (see Enforced invariants). Remaining: serve attaches only `AuthAuditSource` (signed activity, no grants), so production inspect does not yet feed the grant source. **Compose, don't replace** (keep `AuthAuditSource` for signed activity; add the grant source for `granted_for_capsule`); at serve site-1 use the local `audit_log` (infra is partially moved). | *Pending serve wiring* (projection + fold already enforced; a hand-set field would be vacuous). | serve composes the grant source into the inspector; a running capsule with a real grant shows it via the live path. | | G2b | Launch-time verification not wired into the **serve** path | The verifier now resolves a signer and the projection surfaces it (see Enforced invariants), but the serve launch path (`serve_cmd.rs`) registers capsules without verifying, so production *running* capsules carry no `verified_signer` yet. **Blocked on confirming the content-hash domain** (`runtime.rs` hashes `path.join(entrypoint)`; a MicroVM's signed artifact may differ, so a fail-closed serve abort could reject legitimately-signed capsules). | *Pending serve wiring* (no live test until serve threads `verified_signer`; a hand-set field would be vacuous). | serve verifies at launch (content-hash domain confirmed) and threads `verified_signer` onto `RunningCapsuleInfo`; a test drives the running path and a live capsule shows `verified`. | | G3 | Invoke **dispatch** (the "act" half) | Preview-only by design. Dispatch must consult DDRM's `required_action_for` so preview and enforcement agree by construction. **Core DONE (`1b32cae0`)** — see Enforced invariants: the act leg executes and a real executed-gate test proves a token sized to the PREVIEWED action passes the actual op's gate + reaches the provider, while a wrong-action token is denied before dispatch; a conformance pin binds manifest-preview to verb-map enforcement for the rights fixture. Remaining = **G3b**. | n/a — enforced by `carrier_bridge::tests::carrier_rights_op_gate_enforces_exactly_the_previewed_action` + `rights_fixture_preview_actions_match_verb_map`. | **G3b — UNIVERSAL PIN LANDED `W3b-turn` (drift-can-hide CLOSED); per-op resolution follow-up.** `carrier_bridge::tests::all_provider_manifests_preview_actions_match_verb_map_or_tracked` now enumerates EVERY shipped provider manifest (22 with authority) and asserts, for every declared op, that the verb-map-enforced action is a MEMBER of the manifest's previewed action set — keeping the two tables DISJOINT (Option B), so NEW drift fails CI and a silently-fixed op (removed from the ledger without a real fix) also fails. A 4-agent classification swarm triaged the 49 existing drifts into a documented `known_divergences` ledger (read-safe / write / execute-egress / manifest-over-declares / HIGH-RISK-keep-Admin). ALL 49 are fail-CLOSED today (previewed-but-denied — never an escalation). The per-op RESOLUTION is being DRAINED (NOT a bulk loosen): **36 of 49 resolved so far** — ch1 verb-map completion (11); ch2 manifest splits did/ai/llama/tunnel (12); ch3 egress net/exit + encrypt (8); ch4 browser-actuator split (5: launch/attach_stream/close_page/input/webrtc_signal declare `execute` — swarm-confirmed UI-actuation, sandbox-scoped, NOT Admin; dead `write` dropped). **13 remain in the ledger** — the dangerous tail held at Admin/tracked: drm `open`, encrypt `seal`, wallet signing/approval/secret-export (5), key `release`, decrypt open_session/render (2), chain broadcast/prepare_transaction (2), object `share` (access-granting). NOTE (Miller): `did get_persona_did` now previews Read (matches the EXISTING Read enforcement), but its impl can create-a-persona on first call (Write semantics) — a SEPARATE pre-existing verb-map concern (Read under-protects creation), tracked for a dedicated decision, not a G3b drift. Below was the design decision that shaped it: **Option B (disjoint-tables cross-check), NOT a shared table.** A 0.01% swarm proposed collapsing preview (manifest authority) + enforce (verb map) into ONE `canonical_op_action_for` table; the principles seat REJECTED it: collapsing makes the conformance test VACUOUS (it would compare the table to itself) and loses the load-bearing G3-core invariant that the two tables are *disjoint with no shared function so drift fails loudly*. Correct plan: keep them disjoint; generalize the rights fixture to a UNIVERSAL conformance test that enumerates EVERY shipped provider manifest and asserts `invoke::plan_provider_operation(op).actions == {required_action_for(op)}` for every declared op. EVIDENCE (swarm): ~30-40 ops (`reconstruct_listing`, `add_bytes`, `get_bytes`, `seal`, `export_managed_secret`, `download`, `share`…) fall through to `Admin` in the verb map while manifests declare read/write — real preview≠enforce divergences (fail-CLOSED today: user is shown read but denied at enforce). Closing each requires a per-op SECURITY judgement to add the verb-map entry (loosens Admin→Read/Write) — a vetted set, NOT a bulk sweep (ideally its own security sub-swarm). Plus the affordance.operation path (latent capsule-inspector `view`->Admin divergence). Anchors: `provider_resource::required_action_for` (verb map), `invoke::plan_provider_operation` (preview), the rights pin in `carrier_bridge.rs`. | @@ -43,11 +45,14 @@ green, and the row moves to "Closed." | ENV-1 | **(build, aarch64)** an unqualified full-workspace `clippy`/`test` does NOT build on aarch64 — a `c_char` signedness break in `elastos-guest` | `elastos-guest/src/runtime.rs:980` calls `std::ffi::CStr::from_ptr(name.as_ptr())` where `name` is hardcoded `i8`/`*const i8`, but on **aarch64 `c_char` is `u8`**, so `from_ptr` expects `*const u8` → `error[E0308]: mismatched types` (also the `openpty`/`ptsname` site ~2161). NOT a W1b regression — proven pre-existing on clean HEAD (stash-on-clean-HEAD reproduces it; `setup.rs` has 0 overlap with the W1b diff) and arch-specific (x86_64 `c_char = i8` compiles). It blocks `cargo clippy --workspace --all-targets` + `cargo test --workspace` on the KVM box (the `lib test` target fails to compile), which is why the W1b gates were SCOPED to the touched crates (`elastos-crosvm`/`elastos-server`, both clean under `--all-targets -D warnings`). Sibling: 3 `setup::tests` checksum tests also fail on the box (environmental, same stash-proof). | n/a — build break, not a ratchet. | Use `libc::c_char` (not a hardcoded `i8`) for the `ptsname`/`openpty` name buffer so it is correct on both arches; then an unqualified `--workspace --all-targets` clippy/test is green on aarch64 too. Low-risk, isolated to `elastos-guest`. | | G-EGR-TIDY | **(Low, cleanliness)** the per-VM egress nft table is not removed on VM teardown — an empty `table inet elastos_egress` shell persists | Observed during BUG-3 box validation (`flint`, 2026-06-30): after egress-firewall teardown the per-TAP `in_`/`fw_` CHAINS are gone but the base `table inet elastos_egress` remains as an EMPTY shell (`nft list table inet elastos_egress` → `{ }`). BENIGN — it references no TAP, holds no rule, enforces nothing, and so poses no guardrail-#3 mis-gating hazard on a recycled TAP. NOT a BUG-2/3/7 regression and NOT created by the BUG-3 test (which fails at `TUNSETIFF` before any `nft` apply); pre-existing from an earlier act-emitter/C4 run that left the empty base table. | n/a — cosmetic; would be a post-teardown `nft list table inet elastos_egress` is-empty/absent check. | The firewall teardown also drops the now-empty `table inet elastos_egress` when no other live VM references it (refcount the base table) — OR document the persistent empty base table as intentional (created-once, reused). Either resolves the "mystery leftover" without changing enforcement. | | G-AUTH-LOCAL | **(security-review pin, not a default-reachable hole)** a Home-launch token with `proof_binding_id: None` and `app = system` passes the gateway validator on signature + app + expiry ALONE — the live auth-session check (`is_auth_session_active`) is SKIPPED for proof-unbound tokens | Discovered during W5b browser-lane bring-up (`flint`, 2026-06-30): `require_home_launch_token_for_any_from` (`gateway_home_token.rs:339`) only calls `is_auth_session_active` when `proof_binding_id.is_some()`, so a validly-signed proof-unbound SYSTEM token (the "local" context) reaches `inspect/capsules`+`inspect/capsule`+`catalog` with NO live grant. This is an EXISTING validator branch (NOT introduced by W5b); it is the path that makes the local/operator (`runtime_kind: operator`, no passkey) shells work. It is NOT default-reachable by an untrusted capsule (minting requires the runtime DID signing key on disk; the shipped binary mints SYSTEM tokens only via the passkey/wallet `issue_home_launch_token_for_auth_grant` grant path — the no-grant `issue_home_launch_token` is `#[cfg(test)]`). The W5b confirmation used a sanctioned `#[cfg(test)]` mint of exactly such a token. | n/a — would be a validator test asserting a proof-unbound SYSTEM token is accepted ONLY under the intended local/operator posture (and rejected/elevated otherwise). | Confirm the production posture for proof-unbound SYSTEM tokens: either (a) document local/operator-only acceptance as intentional (key-on-disk == operator authority) and gate it on `runtime_kind`, or (b) require a live session/grant for `app = system` even when proof-unbound. Decide before shipping a multi-tenant/remote gateway. | -| G-CARRIER-PEER | **(audit T1) Carrier `provider_invoke` plane has NO peer authentication** — now LOCKED to read-only (writes + key/decrypt/drm/rights refused) | Audit swarm 2026-07-02 (Sol, CONFIRMED): `handle_file_connection` (`carrier.rs`) accepts every inbound `CARRIER_ALPN` connection with no DID allow-list / no peer auth, and `validate_carrier_provider_invocation` is self-referential (it checks caller-supplied envelope fields against each other, NOT against a runtime-issued capability). So anything reachable on the plane was reachable by any anonymous remote peer — including `content:publish`/`import_exact` (unauthorized write + quota-attribution abuse under a caller-supplied `principal_id`) and, as the CRITICAL caveat, the `key`/`decrypt`/`drm` targets. **INTERIM LOCK LANDED `flint-0.5` (2026-07-02):** `carrier_provider_plane_allows_unauthenticated` is a strict default-DENY allowlist — only `content:{fetch,status,admission}` (non-mutating reads) pass; ALL writes and ALL key/decrypt/drm/rights/availability ops are refused with `unauthorized_provider_operation` BEFORE `send_raw`. This closes the confirmed anonymous-write hole and the key-material caveat. | Enforced by `carrier::tests::test_carrier_provider_invoke_refuses_write_op_on_anonymous_plane` (content:publish refused) + `..._refuses_key_material_ops_on_anonymous_plane` (key/decrypt/drm refused) + the existing `..._dispatches_runtime_enveloped_request` (content:fetch still passes). | Real Carrier **peer authentication** (verify the iroh remote node id against an allow-list / require a signed request envelope at `handle_file_connection`) + a verified principal injected for quota, so authenticated push-replication and cross-node key/rights flows can be re-enabled by widening the allowlist. Until then the plane stays read-only. | +| G-M8 | **(Flint S32 — honesty bound) The mandate `responsible_entity` DID is operator-ASSERTED, never attested** | Sprint 32 binds a `responsible_entity: Option` (a liability DID) into the `CapabilityGrant` audit event and the portable `MandateReceipt`, so a revoked/abused mandate carries WHICH entity the operator DECLARED accountable. The value is validated SYNTACTICALLY ONLY (`validate_responsible_entity`: `did::`, ≤256, restricted charset; path/query/fragment rejected) — it is NEVER authenticated: the named entity does not counter-sign the grant, so the runtime cannot prove the entity CONSENTED to the mandate, only that the operator wrote its DID down. The receipt is authoritative; the MandateCard field and the shell chip are MIRRORS. Everywhere the string is surfaced (docs Grant/Prove rows, the doc-comments on the input + card, the shell chip/label titles, the receipt drawer) says "declared by the operator" / "operator-asserted, not attested" — over-claiming it as "proves WHO was accountable" is a P12 honesty violation and was explicitly folded OUT (council F2). Back-compat is load-bearing and closed by construction: the field is appended LAST with `#[serde(default, skip_serializing_if = "Option::is_none")]`, so a pre-S32 grant re-serializes byte-identically and no pre-S32 signed chain breaks (proven by `audit::tests::a_signed_chain_mixing_pre_and_post_s32_grants_verifies` + `..._is_present_when_set_and_omitted_for_back_compat`). | n/a — the honesty bound is enforced by the wording (docs/comments/pixels) + the syntactic-only validator ratchet `handlers::capability::tests::responsible_entity_validation_is_syntactic_and_fail_closed`; the OPEN gap is the missing attestation, which would be a test asserting the named entity counter-signed the grant. | Add an entity-attestation step: the named `responsible_entity` counter-signs (or delegates a signed acceptance of) the mandate at grant time, and `verify-receipt` checks that signature — turning "the operator DECLARED X accountable" into "X ACCEPTED accountability." Until then the bound stays operator-asserted and every surface must say so. | +| MKT-DRM | **(Flint S34/S35/S36 — the DRM wedge's residuals) S36 CLOSED meter-unit⇄price; S35 CLOSED confirmation-depth + cross-window double-buy; royalty verification open** | Sprint 34 wired `DrmMarketplaceProvider` behind the `PaymentProvider` trait (KID→tokenId through the MKT-1-hardened resolver, FAIL-CLOSED on ambiguity; two-generals; tx hash + `operative:tokenId` on the signed `CapabilityUse.rail_ref` → portable receipt). **Sprint 35 made settlement CONFIRMATION-AWARE and closed the two sharpest residuals:** (0, was council S34 red-team F2 — cross-window double-buy) **CLOSED (hardened by the S35 council fold)** — three layers now hold the invariant: (i) the `runtime.pay` closure refuses to re-charge a `flint-` key that already carries a money-bearing entry (`Performed`/`Pending`/`ResolvedCharged`); (ii) **record-before-broadcast** (council S35 red-team F1): the closure durably custodies the key as `Pending` via `PaymentLedger::begin_attempt` BEFORE any money moves, and if the ledger cannot custody it (per-capsule pending cap, ledger full of money-bearing keys, persist failure) it REFUNDS and DECLINES without broadcasting — money never moves into an unrecordable state, so the dedup can never be blind on a re-dispatch; (iii) **money-bearing keys are NEVER evicted** (council S35 guardian F3): only provably-nothing-moved terminals (`NotCharged`/`ResolvedNotCharged`) are evictable, so an eviction can never forget a charged key and reopen the double-buy — a cap full of money-bearing keys refuses new inserts fail-closed (which, via (ii), refuses the broadcast). Proven by `capability::tests::a_redispatched_drm_buy_is_idempotent_and_never_settles_twice` (a counting settler runs EXACTLY once), `payment_ledger::tests::{money_bearing_keys_are_never_evicted, begin_attempt_custodies_reopens_and_refuses}`. Residual (bounded): a runtime CRASH between `begin_attempt` and the broadcast still leaves the S29-class orphaned reservation (custodied `Pending`, recovered via reconciliation) — the key exists, so a re-dispatch is refused; no double-buy. (2, was council S34 guardian F1 — broadcast≠confirmed) **CLOSED** — a DRM buy is now recorded `Pending` at broadcast (NEVER `Performed`), and `reconcile_drm_confirmations` promotes it to charged + binds the receipt `rail_ref` ONLY after `chain_tx::tx_confirmation_live` reads the tx mined + `status==0x1` + at least `ELASTOS_DRM_MIN_CONFIRMATIONS` (default 3) deep; a reverted tx refunds exactly once; a not-yet-mined/unreadable tx stays Pending (never auto-charged, fail-safe). The depth floor gates BOTH verdicts (a shallow revert is HELD, not refunded — a reorg could re-include it successfully; council S35 guardian F2), and an absent/unparseable receipt `status` reads as HOLD, never success (council S35 red-team F3/guardian F1). Reuses the S30 `reconcile_payment_core` spine. Proven by `drm_marketplace::tests::reconcile_drm_confirmations_promotes_refunds_and_holds`, `chain_tx::confirmation_tests::classify_receipt_is_fail_closed_on_status_and_depth`, + the e2e `capability::tests::a_drm_buy_is_pending_until_confirmed_then_the_receipt_carries_the_rail_ref`; back-compat for the new `PaymentRecord.token_id` (`payment_ledger::tests::pre_s35_ledger_snapshot_without_token_id_round_trips`) + `CapabilityUse.rail_ref` (`audit::tests::{rail_ref_is_present_when_set_and_omitted_for_back_compat, a_signed_chain_mixing_pre_and_post_s34_uses_verifies}`) — both skip_serializing_if, appended last. **Residuals, by number (CLOSED ones marked; 2c/3 remain open):** (1) **CLOSED (Sprint 36 — the price gate)** — the DRM provider now QUOTES the on-chain price read-only before broadcast and refuses a buy whose mandate cap `amount × ELASTOS_DRM_SPEND_UNIT` (the declared meter-unit⇄pay-token mapping) does not cover the price, binding the gated price as the buy's expected price (abort-on-drift). The live Chain rail REFUSES TO WIRE without `ELASTOS_DRM_SPEND_UNIT` (fail-closed, no silent 1:1), and the receipt's `rail_ref` now names `price=;tok=`. Proven by `drm_marketplace::tests::{a_buy_below_the_on_chain_price_is_refused_before_broadcast, an_exact_match_buy_proceeds_and_the_rail_ref_names_the_price, an_unparseable_price_is_refused_before_broadcast}` + `server::tests::drm_rail_obeys_the_mock_money_discipline` (the unit-mapping wire refusal). The buy PINS quantity=1 (a pay-for-access buy is one ACCESS_TOKEN; the per-unit gate is the total charge — no `ELASTOS_DDRM_BUY_QUANTITY` env can inflate it) and arms abort-on-drift on BOTH price and pay-token (council S36 fold, red-team F1/F2 + guardian F1/F2/F3); the live rail additionally requires `ELASTOS_DRM_PAY_TOKEN` and refuses a listing in any other token. Proven by `drm_marketplace::tests::{the_drm_buy_target_pins_quantity_and_arms_price_and_pay_token_drift, a_listing_in_a_different_pay_token_than_declared_is_refused}` + the extended `drm_rail_obeys_the_mock_money_discipline`. RESIDUAL: the unit mapping + pay-token are operator-DECLARED (the runtime does not read the pay-token's decimals on-chain) — a wrong declaration mis-scales the ceiling. (2b) **CLOSED (Sprint 37 — the confirmation scheduler)** — the runtime now drives the confirmation poll itself: `ELASTOS_DRM_RECONCILE_INTERVAL_SECS` arms a periodic tick over the SAME `reconcile_drm_confirmations` pass (zero new money-moving code), bounded per tick (`ELASTOS_DRM_RECONCILE_BATCH`, default 64, oldest-first, overflow counted as `skipped`), panic-isolated per entry (a poisoned entry is HELD and the tick continues), idempotent across overlapping passes (the ledger's resolve-exactly-once), OFF by default (no ambient chain poller; malformed env refuses to arm, fail-closed), starvation-proof (a rotating cursor visits every pending within ceil(pending/batch) ticks — a stuck-unconfirmed prefix cannot shadow the entries behind it), non-wedging (at most one tick in flight; a hung RPC is skipped loudly, never stacked), and attested (a SETTLING tick appends a best-effort signed `drm_reconcile_tick` event; idle and held-only ticks are silent, so a stuck pending cannot grow the chain per tick). Proven by `drm_marketplace::tests::{a_tick_is_bounded_oldest_first_and_reports_what_it_skipped, a_stuck_oldest_entry_cannot_starve_the_entries_behind_it, a_panicking_confirmer_holds_that_entry_and_the_tick_continues, only_a_settling_tick_is_attested_held_and_idle_ticks_are_silent}` + `server::tests::the_drm_scheduler_arms_only_with_an_interval_and_a_drm_rail`. RESIDUALS: opt-in by design — a deployment that never sets the interval is back to the manual loop, and the S35 per-capsule pending-quota pressure returns with it; the chain-read deadline is **CLOSED (Sprint 40)** — `run_chain_capsule` now kills a hung provider (process GROUP and all — a helper child cannot keep the pipe open) at `ELASTOS_CHAIN_READ_DEADLINE_SECS` (default 30s; malformed ⇒ default, loudly) and always reaps; the deadline error classifies INDETERMINATE on the send leg (never a refund) and ordinary fail-closed refusal/hold on read legs — and **Sprint 43 made that classification TYPED, not string-sniffed** (see the S43 CLOSED note below): `buy_access` now returns a `BuyError::{PreBroadcast,Indeterminate}` decided by the code path, so a send-leg failure is `Indeterminate` by construction regardless of its bytes; proven by `rights_authority::tests::{a_hung_chain_provider_is_killed_at_the_deadline, a_malformed_deadline_env_keeps_the_default_protection}` (unix kill, like the flock protections — elsewhere the watchdog is a stated no-op) and the response line is length-capped (`MAX_CAPSULE_LINE`, so a firehose provider is a bounded error, not an OOM); the sibling providers are now bounded too (Sprint 41 — the wallet SIGN leg and rights DECIDE leg share one `capsule_watchdog`): a wallet-sign timeout is a PRE-broadcast NotCharged/refund (mirror of the send-leg rule, typed by construction since S43: `buy_authority::a_wallet_sign_timeout_types_the_buy_as_pre_broadcast`), a rights-decide timeout DENIES access (`rights_authority::a_hung_rights_provider_is_killed_and_access_is_denied`, and the money-critical sign leg has its OWN live-kill ratchet `wallet_signer::a_hung_wallet_provider_is_killed_and_classified_pre_broadcast`) — every **chain-read, wallet-sign, and rights-decide** provider conversation the pay/access pipeline traverses is now bounded INCLUDING the reap (an answered-then-lingering child is group-killed after a short grace via `capsule_watchdog::reap_grouped`, never parked on `wait()` — council S41 guardian F1/F2). RESIDUAL (council S41 guardian F3) **CLOSED (Sprint 42)**: the access-path *sidecar* helpers outside those three provider conversations — the media/object authorities (launch + quorum descriptor reads AND the per-op segment/page/object VIEW reads) and the grant sidecar (`access_grant::run_sidecar`) — are now on the SAME `capsule_watchdog`: reads go through `read_line_deadlined` (arm → length-capped read → disarm; a fire DENIES fail-closed), the one-shot grant read is bounded read-to-EOF under the watchdog, every spawn is `spawn_grouped`, and every reap (Drop + the early-return `ChildReaper`) is the bounded `reap_grouped`, so a hung/hostile content sidecar can no longer park a request thread and a deadline kill leaves no zombie. A content-open/view timeout is a DENY (the mirror of the rights-decide rule), never a money decision (these are open/view paths, not the pay spine). Proven by `object_authority::a_hung_object_authority_is_killed_and_access_is_denied`, `media_authority::a_hung_media_authority_is_killed_and_access_is_denied`, `object_authority::a_hung_object_view_read_is_bounded_and_denied` (the per-op VIEW leg, distinct from the open), `access_grant::a_hung_grant_sidecar_is_killed_and_the_open_fails_closed`. CLOSED (Sprint 46, was council S42 guardian F8): `access_grant::prepare`/`assemble` AND `assemble_cached` (the popup-free re-open path the S46 guardian caught still on the async executor) now run inside `tokio::task::spawn_blocking` in `viewer_open` — the (deadline-bounded, ≤~31s) sidecar wait holds a blocking-pool thread, never an async worker; a panicked task maps to the same error arm each site already had (fail-closed for prepare/assemble; fall-back-to-enrolled-path for the cached re-open, whose authorization gate already passed). The dev-modes construction ratchets (S43 typed BuyError + the S46 prepare-leg deadline) are now COMPILED BY THE GATE — `just _verify-tail` and ci.yml both run the `--features dev-modes` lib lane (council S46 guardian F3: a ratchet outside the gate cannot ratchet). The tick-summary event is best-effort (a lost emit under-reports the tick, never the money — `payment_reconciled` is the durable attestation). (2c, council S35 red-team F4) the confirm-time receipt binding (the token-keyed `CapabilityUse.rail_ref`) is best-effort: if that emit fails the entry is still `ResolvedCharged` and the settlement is durably attested by the `payment_reconciled` chain event, but the receipt's `rail_ref` is absent — a lost-emit under-report, never a hidden settlement. (2d, council S35 red-team F5) **CLOSED (Sprint 44)** — the DRM reconciler no longer sniffs the `drm:tx=` note prefix to identify its records; a STRUCTURED `PaymentRail::{Unknown, Http, Drm}` tag is stamped on each `PaymentRecord` from the paying provider at `begin_attempt` (`DrmMarketplaceProvider::rail() == Drm`, `HttpPaymentProvider::rail() == Http`), and `reconcile_drm_confirmations` selects by that tag (`is_drm_pending`). A positively-tagged `Http` pending — even one whose Indeterminate body a hostile endpoint crafted to begin `drm:tx=` — is NEVER polled by the DRM driver. BOUNDED LEGACY FALLBACK: a pre-S44 record is `Unknown` (untagged, `#[serde(default)]`) and still falls back to the note heuristic so in-flight pendings reconcile across the upgrade; that carries the old fail-closed (refund/hold only) exposure but ONLY for pre-S44 records, which drain. Proven by `drm_marketplace::a_positively_tagged_http_pending_is_never_reconciled_by_the_drm_driver` + `payment_ledger::a_pre_s44_record_without_rail_deserializes_as_unknown_and_gains_the_tag`. **(refund classifier) CLOSED (Sprint 43)** — the refund-vs-hold decision no longer sniffs `buy_access`'s error STRING (the `is_pre_broadcast_refusal` substring classifier + its `chain-provider op failed` exclusion + the pre-broadcast sentinel list are DELETED). `buy_access` now returns a TYPED `BuyError::{PreBroadcast, Indeterminate}` decided BY CONSTRUCTION — which code path produced the error — and `DrmSettleError::from_buy_error` maps the variant. A broadcast-op failure can only ever be built as `Indeterminate` at its single call site, so no provider-controlled message (not even one embedding every pre-broadcast sentinel) can flip a possibly-sent tx into a refund; the one unbreakable invariant is now a TYPE property. Proven by `drm_marketplace::from_buy_error_classifies_by_variant_not_by_string` (the hostile-sentinel-in-Indeterminate holds), `buy_authority::{a_broadcast_op_error_types_the_buy_as_indeterminate_even_with_a_sentinel, a_wallet_sign_timeout_types_the_buy_as_pre_broadcast, a_post_broadcast_record_failure_types_the_buy_as_indeterminate, a_dev_record_failure_types_the_buy_as_pre_broadcast, chain_buy_without_wallet_fails_closed}`. SIDE BENEFIT (strictly more precise than the string classifier, all in the safe-or-refund direction): a chain deadline on the PREPARE (read) leg is now correctly refundable while the same marker on the SEND leg stays held — a distinction the string could not draw. The prepare leg now has its DEDICATED ratchet (Sprint 46, closing council S43 guardian F2): `buy_authority::a_chain_prepare_deadline_types_the_buy_as_pre_broadcast` — a chain stub answers the listing read then hangs only on `prepare_transaction`; the buy is killed at the deadline and typed `PreBroadcast` ⇒ refund, carrying the SAME `CHAIN_DEADLINE_MARKER` the send leg holds as Indeterminate (the call site decides, not the bytes) — guarding the ordering invariant a refactor could break (hoisting the prepare out of the sign closure). The P16 residual (S43 guardian F4) is PARTIALLY closed (Sprint 46): the runtime-only SECRETS — `ELASTOS_DDRM_BUY_SIGNED_TX` (a broadcastable signed tx) and `ELASTOS_PAYMENT_TOKEN` (the rail bearer) — are now STRIPPED from every capsule spawn seam — `capsule_watchdog::spawn_grouped` (chain/wallet/rights/content sidecars), `ProviderBridge::spawn` (the general provider capsules), the carrier service spawn, and the shell-capsule spawns (the S46 council red-team/guardian F1 proved the first cut's single-seam claim FALSE: the provider/carrier/shell seams bypassed it and inherited the rail bearer; all are now stripped from ONE shared list, `elastos_runtime::provider::RUNTIME_ONLY_SECRETS`). Proven by `capsule_watchdog::runtime_only_secrets_are_stripped_from_spawned_capsules` (the strip works; ordinary `ELASTOS_*` config passes through) + the SOURCE-STRUCTURAL guard `capsule_watchdog::every_command_spawn_site_is_a_known_seam_and_capsule_seams_strip_secrets` (every `Command::new` site in elastos-server/elastos-runtime must be a classified capsule-seam-with-strip or host-tool — a NEW spawn path fails the gate until consciously classified). A FULL per-capsule env allowlist (each capsule declares what it may read) remains the stronger tracked hardening. (3) Royalty-split correctness (INV-* of the DRM protocol) is the protocol's, not re-verified by Flint. The live Base path (`ChainDrmMarketplace` resolve/settle/confirm) is compiled and now has an OPERATOR/CI live-buy integration test — `crates/elastos-server/tests/live_drm_buy.rs`, gated behind the `live-chain` cargo feature and `#[ignore]`d (drives the real chain per `docs/LIVE_BUY_RUNBOOK.md`; asserts the buy is HELD `Indeterminate` with a real `drm:tx=`, never charged at broadcast, then confirms on-chain). It is NEVER in the default gate (no funded wallet / live RPC), and **has not yet been run against a live testnet in this repo** — the first operator run should record its tx hash here. The gate-runnable half — that a confirmed DRM buy's receipt is an admissible artifact through the standalone `verify-receipt` CLI (AUTHENTIC with the pinned signer; INVALID if the settlement reference is edited) — DOES run every push: `verify_receipt_cmd::{a_drm_settlement_receipt_verifies_authentic_through_the_cli, a_tampered_drm_rail_ref_is_invalid_through_the_cli}` (Sprint 45). What remains operator-only is spending real value against a live listing; royalty-split correctness is the DRM protocol's, not re-verified by Flint. | n/a — the shipped path is enforced by the S34/S35 ratchets named above; each OPEN residual would get its own: a unit-conversion gate test; a scheduler smoke; a royalty-invariant check. | (1) a meter-unit⇄pay-token conversion (or explicit same-unit assertion) so the cap is a literal on-chain ceiling; (3) optionally assert the DRM protocol's value-conservation invariant post-buy. | +| G-M9 | **(Flint S33 — money-perimeter residuals) The fresh-passkey money gate's three stated bounds** | Sprint 33 closed the S31 F1 residual: the mandates launch token is COOKIE-delivered (HttpOnly, SameSite=Strict, path-scoped to `/api/apps/mandates`; the launch URL carries only a non-secret `shell=1` marker — ratchet `mandates_launch_url_carries_no_token_and_the_cookie_carries_it_instead`), cookie-authorized writes demand the anti-CSRF app-marker header (`cookie_transport_reads_work_and_writes_demand_the_csrf_marker`), and the money writes (spend-budget, reconcile) each require a FRESH proof-bound passkey verification (≤180s, same principal — the wallet-send gate) that is SPENT on exactly one write (`money_write_with_the_standing_token_alone_is_refused`, `fresh_passkey_verification_is_single_use_across_money_verbs`). THREE residuals are deliberately stated rather than hidden: (1) the spent-token guard is IN-MEMORY — a gateway restart inside the ~3-minute freshness window could admit ONE replay of an already-used verification (durable single-use consumption, e.g. on the audit chain or a small fsync'd journal, is the close); (2) ISSUE is not fresh-bound — mint keeps the S15 posture (admin refused, bound key + responsible entity required, shell-token gated); extending the fresh gate to the authority-GRANTING verb is a product decision (friction on every grant) to make deliberately, and REVOKE must stay low-friction by design (the kill switch); (3) the no-passkey/local-operator posture cannot make WEB money writes at all — fail-closed to CLI/consent-broker (stated in the panel), which is honest but means the web Money panel is read-only for that posture. Sibling honesty bounds: (a) the fresh token is NOT verb/capsule-scoped at mint — single-use consumption is what stops a second write, and every surface says "one verification = one write" rather than claiming mint-time scoping; (b) the single-use guard keys on the SHA-256 of the CANONICAL payload the signature covers, NEVER the raw token string (S33 council guardian F1, the fold's ship-blocker: the same assertion re-encoded into byte-different strings — whitespace, field order — still VERIFIES, so a raw-string key would have let one ceremony authorize unlimited re-encoded replays; ratchet `a_re_encoded_spent_verification_is_still_spent` proves the re-encoding passes verification and is refused by the GUARD); (c) a refusal provably BEFORE any money effect (rail unwired, over-ceiling, the cores' 4xx pre-effect rejections) RE-CREDITS the ceremony — same contract as the carrier's `DidNotAct` refunds — while any 5xx keeps it spent (may have acted; mirrors indeterminate-keeps-reservation); ratchet `a_pre_effect_refusal_re_credits_the_fresh_verification` (S33 council red-team F1); (d) the wallet surface's own fresh gate (send/export/approvals) still permits token REUSE within its 180s window AND does not share the mandates guard — one fresh token in an attacker's hands buys its wallet actions plus ONE mandates money write (S33 red-team F2); a single shared single-use consume across ALL fresh-passkey surfaces is the follow-on. | n/a — the shipped halves are enforced by the four S33 ratchets named in the gap; the OPEN residuals would each get their own ratchet (a restart-replay test against a durable guard; an issue-with-fresh-gate test; a wallet single-use test). | (1) durable spent-token journal (or chain-attested consumption) so a restart cannot admit a replay; (2) a deliberate decision + ratchet on fresh-binding ISSUE; (3) one SHARED single-use consume across all fresh-passkey surfaces (wallet send/export/approvals + mandates money). | +| G-CARRIER-PEER | **(audit T1) Carrier `provider_invoke` plane has NO peer authentication** — now LOCKED to read-only (writes + key/decrypt/drm/rights refused) | Audit swarm 2026-07-02 (Sol, CONFIRMED): `handle_file_connection` (`carrier.rs`) accepts every inbound `CARRIER_ALPN` connection with no DID allow-list / no peer auth, and `validate_carrier_provider_invocation` is self-referential (it checks caller-supplied envelope fields against each other, NOT against a runtime-issued capability). So anything reachable on the plane was reachable by any anonymous remote peer — including `content:publish`/`import_exact` (unauthorized write + quota-attribution abuse under a caller-supplied `principal_id`) and, as the CRITICAL caveat, the `key`/`decrypt`/`drm` targets. **INTERIM LOCK LANDED `flint-0.5` (2026-07-02):** `carrier_provider_plane_allows_unauthenticated` is a strict default-DENY allowlist — only `content:{fetch,status,admission}` (non-mutating reads) pass; ALL writes and ALL key/decrypt/drm/rights/availability ops are refused with `unauthorized_provider_operation` BEFORE `send_raw`. This closes the confirmed anonymous-write hole and the key-material caveat. | Enforced by `carrier::tests::test_carrier_provider_invoke_refuses_write_op_on_anonymous_plane` (content:publish refused) + `..._refuses_key_material_ops_on_anonymous_plane` (key/decrypt/drm refused) + the existing `..._dispatches_runtime_enveloped_request` (content:fetch still passes). | **PEER AUTH LANDED (content plane) 2026-07-03:** `handle_file_connection` now captures the iroh-cryptographically-verified `conn.remote_node_id()` (the peer's `did:key`) and threads it to the provider-invoke gate. A peer is authenticated ONLY if its verified DID is on the `ELASTOS_CARRIER_TRUSTED_PEERS` allowlist (empty/unset by default ⇒ fail-closed, every peer stays read-only, zero behavior change until an operator opts a peer in). The verified node-id is encoded into the runtime's canonical `did:key` namespace (`public_key_to_did`, the inverse of `did_to_public_key`), so the allowlist and the quota ledger are one namespace end-to-end; the allowlist accepts either `did:key` or a raw node-id. Authenticated peers get (a) a widened plane — content push-replication WRITES (`publish`/`import_exact`/`import_object`/`ensure`/`unpublish`/`repair`) in addition to the reads — and (b) a **VERIFIED principal injected onto the LOAD-BEARING attribution fields the content coordinator actually reads — `publisher_did` AND `object_did` (not just `principal_id`; `effective_publisher_did` honors a caller-supplied `publisher_did`, so overriding only `principal_id` would have left T1 open — caught by the guardian + red-team)**, so an allowlisted peer can only write content attributed to and owned by ITSELF; the anonymous plane stamps `carrier:anonymous` so no caller-supplied identity is ever honored. Cross-owner push-replication (preserving a different original `object_did`) is a deferred per-flow design. **key/decrypt/drm/rights stay REFUSED even when authenticated** — cross-node key-material flows need their own per-flow capability design (the residual). Enforced by `carrier::tests::{carrier_authenticated_plane_widens_content_writes_but_never_key_material, carrier_trusted_peer_is_fail_closed_and_matches_only_the_allowlist, test_carrier_provider_invoke_authenticated_peer_writes_under_verified_principal, ..._still_refused_key_material, ..._untrusted_peer_stays_read_only}`. **RESIDUAL:** cross-node `key`/`decrypt`/`drm`/`rights` flows (per-flow capability design) + an optional signed-request-envelope layer for defense-in-depth beyond the QUIC-authenticated node-id. | ## Performance + bugs (audit sweep 2026-06-26, swarm `w3y7cu6ao`) -> **SPEED grade 5/10.** The crypto/capability core is fast; the runtime-wide ceiling is two STRUCTURAL I/O costs, not CPU. **How to be fastest (ordered):** (1) MEASURE first (no flamegraph run yet; magnitudes are I/O-class estimates: fsync ms >> verify us >> clone ns); (2) take the FREE win — reflink/COW the rootfs overlay (`supervisor.rs:1152`, O(1) cold launch, zero correctness change); (3) the real ceiling — **audit `fsync`-per-record under a global Mutex on the validate hot path** (`audit.rs:499/543`, ~1/fsync_latency ops/sec, core-count-independent): move to a single writer task + group-commit so K records share one fsync. NON-NEGOTIABLE: never coalesce a custody record (`content_open` keeps flush-now+commit-ack) and never cache a revocation/expiry/use-count check — buy throughput only by batching the events we are allowed to lose. (4) THEN second-order: ed25519 verify LRU (`manager.rs:298`, dwarfed by today's fsync), inspect manifest cache (`inspect_provider.rs:535`). **CONFIRMED BUGS (verify killed none; VM-lifecycle cluster needs a crosvm test env — good local/Cursor candidates):** BUG-1 (high) **CLOSED** — `reap_dead_capsules` trusted `kill(pid,0)` liveness, so a self-exited crosvm child lingered as an un-reaped zombie (`kill(pid,0)` still succeeds for a zombie). `RunningVm::has_exited` now consults the owned child handle via `try_wait()` (reaping the kernel process-table entry), factored into the VM-free `child_has_exited` so the reaping decision is unit-tested without KVM (`elastos-crosvm/src/vm.rs:303-369`, tests `child_has_exited_reaps_a_finished_process` / `_is_false_while_running`); BUG-2 (high) per-launch `-carrier.sock` + detached bridge accept-loop leaked on every teardown (`supervisor.rs:1141`; fix: store+abort the JoinHandle, remove the sock); BUG-3 (high) boot-failure orphan: overlay+sockets+task leaked when `vm.start()` Errs before the running-map insert; BUG-4 (med) **CLOSED (mechanism) `W3b-turn`; real-provider migrations follow-up** — a single-use cap is consumed at `validate()` before `send_raw`, so a provider failure burned the grant on a no-op. An ocap audit (Mark-Miller seat) established that refunding on a general provider `Err` is UNSAFE: **no carrier provider op is atomic on its Err path** (write-then-fail is possible) and `ProviderError::{Provider,NotFound,Io}` cannot distinguish "acted then failed" from "never acted", so a refund there could enable a second execution of a partially-applied write (catastrophic for the actuator/payment classes). TWO refund-safe slices now landed: (1) `ProviderError::NoProvider` (routing failure — the registry invoked NOTHING); (2) the new **`ProviderError::DidNotAct(String)`** — a provider returns it ONLY when it provably rejected before any side effect (precondition/validation failure), so a replay is an idempotent no-op. The carrier refunds the single use on BOTH (saturating `CapabilityStore::refund_token_use` / `CapabilityManager::refund_use`); every other `Err` keeps the use consumed (fail-closed). Test-first: `capability::store::tests::refund_token_use_is_the_saturating_inverse_of_try_use`; `carrier_bridge::tests::carrier_invoke_refunds_single_use_grant_on_missing_provider`; and the op-failure PoC `carrier_invoke_refunds_single_use_grant_on_did_not_act` (DidNotAct refunds — same token reaches the provider twice) + `carrier_invoke_keeps_single_use_consumed_on_acted_failure` (an acted `Provider` failure stays consumed). The `DidNotAct` ocap contract is documented on the variant; `Display` + the storage `From` (→ 400-class `InvalidPath`) updated. **FOLLOW-UP (per-provider, draining):** migrate real providers to return `DidNotAct` on their provably-pre-mutation rejections. **FIRST REAL MIGRATION DONE `W3b-turn`:** the carrier-only `CarrierGossipProvider` (`peer` scheme — swarm-confirmed no gateway consumes its `send_raw` error shape) now returns `DidNotAct` for the pre-effect empty-topic rejection in `gossip_join`/`gossip_leave` (the request-shape check happens before any join/remove), proven by `carrier::tests::gossip_join_and_leave_empty_topic_return_did_not_act` against the REAL provider; its `join_failed` path stays `Provider` (may have partially acted). **SECOND MIGRATION + more rejections DONE `W3b-turn`:** `CarrierAvailabilityProvider` (`availability`, carrier-only) returns `DidNotAct` for its pre-effect request-shape rejections (missing/invalid `cid` on `ensure`/`repair`, missing/invalid `cid` + invalid `path` on `fetch`); `CarrierGossipProvider` `gossip_join` now also returns `DidNotAct` for its `already_joined` + `too_many_topics` no-op rejections. Proven by `carrier::tests::carrier_availability_request_shape_rejections_return_did_not_act` (real provider, missing-cid + invalid-cid). The Miller-seat audit FLAGGED `gossip_leave`'s `not_joined` as UNSAFE (three `remove()` calls execute BEFORE the check), so it stays a structured `Ok` error. **CONTRACT REFINED + CONTENT MIGRATION `W3b-turn`:** a swarm + ocap review sharpened the `DidNotAct` contract — a refund is safe ONLY when nothing acted AND a REPLAY is a GUARANTEED no-op (a property of the REQUEST, or of a STABLE state like `already_joined`), NOT a TRANSIENT capacity/quota condition (a replay could ACT once capacity frees). Accordingly the prior `gossip_join` `too_many_topics` migration was REVERTED to a structured error (kept `already_joined`, which is a stable no-op); the variant doc now states this rule. Third real migration: `ContentProvider` (`content`, carrier-only) `fetch` now returns `DidNotAct` for its request-shape rejections (missing/invalid cid, invalid path — all pre-effect, before any registry/IPFS fetch), proven by `content::tests::content_fetch_rejects_invalid_cid_and_path` against the real provider. ContentProvider WRITE-path request-shape rejections now also DidNotAct: `import_exact` (invalid cid) and `publish` file (missing data) — both pre-effect (before the IPFS add), proven by `content::tests::content_write_request_shape_rejections_return_did_not_act`; the `storage_quota_exceeded` check correctly STAYS a structured error (capacity = transient, per the refined contract). `publish` request-shape rejections are now fully drained too: `unsupported_content_kind` and directory `files-must-be-array` also return `DidNotAct` (pre-effect, before the IPFS add; covered by the same test). Remaining drainable (noted, lower-value, deferred): only the HELPER-gated `import_exact` validations (`validate_import_exact_invocation`, `import_exact_payload_bytes`) — migrating those means changing shared helper contracts, a wider edit held for a dedicated pass. **The clearly-pre-effect, single-site request-shape rejections across all carrier-only providers (gossip, availability, content) are now DRAINED — the in-cloud BUG-4 frontier is effectively complete.** First-migration candidate `InspectProvider` was VERIFIED `W3b-turn` and is NOT a drop-in: its `send_raw` `Ok(error-status Value)` contract is relied on by BOTH transports (the carrier AND the gateway provider proxy `gateway_provider_proxy.rs:1399`) plus ~21 assertion sites in inspect tests, so emitting `Err(DidNotAct)` is a multi-caller refactor (update the gateway proxy inspect handling + re-decide the error contract on both transports + the tests), not a quick PoC. RECOMMENDATION: the first real migration should instead target a CARRIER-ONLY provider whose `send_raw` error shape no gateway path consumes, OR do InspectProvider as its own scoped chunk. Each migration needs the same per-op "provably no side effect" judgement (the audit is the gate, not a blanket sweep); BUG-5 (med) **CLOSED `W3b-turn`** — the carrier `request_capability` poll loop (sleep-then-check) dropped a grant landing between the last in-loop poll and loop exit, reporting a spurious timeout. Extracted `await_capability_decision` (poll the pending store, then ONE final read after the loop) + a `CapabilityDecision` enum; the carrier bridge now routes through it. Test-first + deterministic (no timing flake): `carrier_bridge::tests::await_capability_decision_catches_a_grant_after_the_loop` runs with `max_polls = 0` so ONLY the trailing read can find the grant (would time-out under the old code), plus a clean-timeout case. RESIDUAL **CLOSED `W3b-turn`**: the WASM **API** bridge's HTTP poll (`handle_remote_request`) had the analogous shape; now routed through a transport-agnostic `poll_then_final_read` (loop + ONE trailing read), so an HTTP grant landing after the last poll is no longer dropped. Tested deterministically WITHOUT a flaky HTTP mock: `carrier_bridge::tests::poll_then_final_read_catches_a_decision_after_the_loop` runs the helper with `max_polls = 0` (loop skipped) so only the trailing read can return the decision — the exact gap the old loop had; BUG-6 (low) **CLOSED `W3b-turn`** — carrier `MAX_LINE_BYTES` was checked AFTER unbounded `read_line`/`.lines()` (an untrusted guest could OOM the host with a newline-less line before the check ran). Fixed with a `take(MAX+1).read_until` bounded reader (`read_bounded_line` async + `read_bounded_line_sync`) that caps allocation DURING the read and drains to the next newline so the stream realigns; wired into ALL THREE bridges (the WASM API bridge previously had no bound at all). Test-first proof: `carrier_bridge::tests::read_bounded_line_*` (oversized rejected + realign, oversized-at-EOF, CRLF, sync twin) over in-memory pipes; BUG-7 (med) reap treats Carrier backend as unconditionally alive; BUG-8 (low) **CLOSED `W3b-turn`** — `next_cid` used an unchecked `*next += 1` (overflow/wrap) with no free-CID scan, so a wrapped counter could re-hand a CID a live VM still held. Replaced with `allocate_cid(from, in_use)`: floors the reserved low CIDs (0/1/2 → guests start at 3), skips any CID in the live `running` set, wraps the u32 space via `checked_add().unwrap_or(MIN_GUEST_CID)`, and fails closed (refuses the launch) if exhausted. Test-first: `supervisor::tests::allocate_cid_*` (reserved floor, skip-live, wrap-without-overflow, wrap-does-not-collide-with-a-live-VM, free-within-bound). Wave-2 structural: the audit group-commit rewrite (measure first) + AUD-4 plane-(a). +> **SPEED grade 5/10.** The crypto/capability core is fast; the runtime-wide ceiling is two STRUCTURAL I/O costs, not CPU. **How to be fastest (ordered):** (1) MEASURE first — **FIRST MEASUREMENT LANDED 2026-07-03** (`benches/audit_emit.rs`, hermetic std-timing, `cargo bench -p elastos-runtime --bench audit_emit`): on a dev SSD the audit `emit` is **~879k ops/s memory-only (1.14 µs)** vs **~789 ops/s file-backed with fsync-per-record (1267 µs) — a ~1113× durable-custody tax and a ~789 durable-emit/s single-writer ceiling**, confirming the estimate's magnitude (fsync ms >> verify us >> clone ns) with a real number. **GROUP COMMIT LANDED `S51` (measured before/after):** on this box the single-writer ceiling measured ~1.1k emits/s (~950 µs/op, ~430× the 2.2 µs CPU cost); with the S51 group commit, 8 CONCURRENT emitters reach ~3.1k emits/s (2.9× the single-writer ceiling — pre-S51 they were PINNED AT it, every emitter serialized behind fsync-per-record). Single-threaded latency is unchanged (one fsync each, nothing to coalesce). The bench's 8-thread regime verifies the full chain after the run, so the number counts CORRECT commits only. Re-run on the target box before relying on magnitudes. (Remaining estimates below are still un-benchmarked.) (2) take the FREE win — reflink/COW the rootfs overlay (`supervisor.rs:1152`, O(1) cold launch, zero correctness change); (3) the real ceiling — **audit `fsync`-per-record under a global Mutex** — **CLOSED `S51` (group commit):** `emit` now appends in chain order under the chain lock, then WAITS until a flusher's `sync_all` (on a cloned fd, so appends continue during the fsync — the writer-mutex convoy was the measured killer of the first two cuts) covers its seq; N concurrent emits share one fsync. THE CONTRACT IS UNCHANGED: `Ok(())` still means THIS record is durable (custody records are never coalesced into a maybe); a failed write/fsync POISONS the log fail-closed (every later emit refuses — which also retires the pre-S51 latent hazard where retrying a failed seq could append a duplicate after a half-landed record). Proven by `audit::tests::{concurrent_emits_group_commit_and_the_chain_stays_perfect, a_failed_durable_write_poisons_the_log_fail_closed}` + the 8-thread bench regime. **S51 COUNCIL FOLD (guardian + red-team, both SHIP-WITH-FIXES; core invariants — Ok⟹durable, anchor-never-over-claims, flusher liveness — independently confirmed sound):** (F1, the one real race) the poison gate was check-then-append — an emit queued on the chain lock during another emit's write failure could re-derive the FAILED seq and append behind its half-landed bytes (a duplicate-seq corruption; every consequence stayed fail-closed but the chain bricked). Closed: the write-failure arm poisons while STILL HOLDING the chain lock and `emit` re-checks poison UNDER the chain lock (chain→flush nesting verified acyclic); ratchet `a_poisoned_log_refuses_before_assigning_a_seq_or_writing`. (F2, both seats) the 'restart re-opens from the durable prefix' claim was NOT implemented — a crash-torn tail (a never-acknowledged final line; provable because an acknowledged record's full `line\n` was fsynced) made the verified open REFUSE a healthy log, and S51's standing flushed-not-yet-fsynced batch widened that window. Closed: `quarantine_torn_tail` at open moves a non-newline-terminated trailing fragment to `.torn-tail` (preserved, never destroyed) and resumes from the intact prefix — safe because it can never remove an acknowledged record and grants a tamperer nothing beyond the anchor floor they didn't already have via a clean line-boundary cut; a mid-file corruption still refuses (tamper). Ratchet `a_torn_tail_is_quarantined_and_the_log_resumes_from_the_durable_prefix`. (F3) flush-mutex panic-poison could strand `flushing=true` (waiters block forever): all flush-lock sites now recover via `PoisonError::into_inner` (FlushState is single-statement-writes valid), a FlusherGuard clears+poisons on unwind, and the loud tracing moved outside the lock. (F4) guardian flagged that a crash can land an EMPTY head anchor and brick a verified open; the fold's first cut fsynced the anchor temp — and the bench REJECTED it (a single-threaded emitter is its own flusher, so it doubled the per-record cost to ~1.7 ms). Final: no anchor fsync; an EMPTY anchor reads as ABSENT (floor skipped for that one open, warned loudly, rewritten by the next flush) — safe because the ≤20-byte single-sector payload is complete-or-empty after a crash, never partial garbage; non-empty garbage stays fail-closed. (F5) `anchored_seq` seeds from max(resumed head, ON-DISK anchor) so an unverified reopen of a truncated log can never regress the anchor downward and destroy truncation evidence. CLOSED (S52, was red-team F5): the file-backed audit log now holds an exclusive advisory flock (Unix advisory flock, like the meter's; non-unix builds have no lock) on `.lock` for its lifetime — the SAME single-opener discipline as the spend meter and payment ledger — so a second live opener is refused `WouldBlock` fail-closed instead of two instances minting the same seqs (ratchet `a_second_live_opener_of_the_same_log_is_refused`; the gateway's lazy audit-log constructor now serializes so its benign both-construct race can't surface a spurious flock refusal). RESIDUAL (accepted): `Err` from emit does not prove the record is absent from disk (inherent fsync ambiguity, unchanged pre/post S51 — an over-record, never a lost one). NON-NEGOTIABLE: never coalesce a custody record (`content_open` keeps flush-now+commit-ack) and never cache a revocation/expiry/use-count check — buy throughput only by batching the events we are allowed to lose. (4) THEN second-order: ed25519 verify LRU (`manager.rs:298`, dwarfed by today's fsync), inspect manifest cache (`inspect_provider.rs:535`). **CONFIRMED BUGS (verify killed none; VM-lifecycle cluster needs a crosvm test env — good local/Cursor candidates):** BUG-1 (high) **CLOSED** — `reap_dead_capsules` trusted `kill(pid,0)` liveness, so a self-exited crosvm child lingered as an un-reaped zombie (`kill(pid,0)` still succeeds for a zombie). `RunningVm::has_exited` now consults the owned child handle via `try_wait()` (reaping the kernel process-table entry), factored into the VM-free `child_has_exited` so the reaping decision is unit-tested without KVM (`elastos-crosvm/src/vm.rs:303-369`, tests `child_has_exited_reaps_a_finished_process` / `_is_false_while_running`); BUG-2 (high) per-launch `-carrier.sock` + detached bridge accept-loop leaked on every teardown (`supervisor.rs:1141`; fix: store+abort the JoinHandle, remove the sock); BUG-3 (high) boot-failure orphan: overlay+sockets+task leaked when `vm.start()` Errs before the running-map insert; BUG-4 (med) **CLOSED (mechanism) `W3b-turn`; real-provider migrations follow-up** — a single-use cap is consumed at `validate()` before `send_raw`, so a provider failure burned the grant on a no-op. An ocap audit (Mark-Miller seat) established that refunding on a general provider `Err` is UNSAFE: **no carrier provider op is atomic on its Err path** (write-then-fail is possible) and `ProviderError::{Provider,NotFound,Io}` cannot distinguish "acted then failed" from "never acted", so a refund there could enable a second execution of a partially-applied write (catastrophic for the actuator/payment classes). TWO refund-safe slices now landed: (1) `ProviderError::NoProvider` (routing failure — the registry invoked NOTHING); (2) the new **`ProviderError::DidNotAct(String)`** — a provider returns it ONLY when it provably rejected before any side effect (precondition/validation failure), so a replay is an idempotent no-op. The carrier refunds the single use on BOTH (saturating `CapabilityStore::refund_token_use` / `CapabilityManager::refund_use`); every other `Err` keeps the use consumed (fail-closed). Test-first: `capability::store::tests::refund_token_use_is_the_saturating_inverse_of_try_use`; `carrier_bridge::tests::carrier_invoke_refunds_single_use_grant_on_missing_provider`; and the op-failure PoC `carrier_invoke_refunds_single_use_grant_on_did_not_act` (DidNotAct refunds — same token reaches the provider twice) + `carrier_invoke_keeps_single_use_consumed_on_acted_failure` (an acted `Provider` failure stays consumed). The `DidNotAct` ocap contract is documented on the variant; `Display` + the storage `From` (→ 400-class `InvalidPath`) updated. **FOLLOW-UP (per-provider, draining):** migrate real providers to return `DidNotAct` on their provably-pre-mutation rejections. **FIRST REAL MIGRATION DONE `W3b-turn`:** the carrier-only `CarrierGossipProvider` (`peer` scheme — swarm-confirmed no gateway consumes its `send_raw` error shape) now returns `DidNotAct` for the pre-effect empty-topic rejection in `gossip_join`/`gossip_leave` (the request-shape check happens before any join/remove), proven by `carrier::tests::gossip_join_and_leave_empty_topic_return_did_not_act` against the REAL provider; its `join_failed` path stays `Provider` (may have partially acted). **SECOND MIGRATION + more rejections DONE `W3b-turn`:** `CarrierAvailabilityProvider` (`availability`, carrier-only) returns `DidNotAct` for its pre-effect request-shape rejections (missing/invalid `cid` on `ensure`/`repair`, missing/invalid `cid` + invalid `path` on `fetch`); `CarrierGossipProvider` `gossip_join` now also returns `DidNotAct` for its `already_joined` + `too_many_topics` no-op rejections. Proven by `carrier::tests::carrier_availability_request_shape_rejections_return_did_not_act` (real provider, missing-cid + invalid-cid). The Miller-seat audit FLAGGED `gossip_leave`'s `not_joined` as UNSAFE (three `remove()` calls execute BEFORE the check), so it stays a structured `Ok` error. **CONTRACT REFINED + CONTENT MIGRATION `W3b-turn`:** a swarm + ocap review sharpened the `DidNotAct` contract — a refund is safe ONLY when nothing acted AND a REPLAY is a GUARANTEED no-op (a property of the REQUEST, or of a STABLE state like `already_joined`), NOT a TRANSIENT capacity/quota condition (a replay could ACT once capacity frees). Accordingly the prior `gossip_join` `too_many_topics` migration was REVERTED to a structured error (kept `already_joined`, which is a stable no-op); the variant doc now states this rule. Third real migration: `ContentProvider` (`content`, carrier-only) `fetch` now returns `DidNotAct` for its request-shape rejections (missing/invalid cid, invalid path — all pre-effect, before any registry/IPFS fetch), proven by `content::tests::content_fetch_rejects_invalid_cid_and_path` against the real provider. ContentProvider WRITE-path request-shape rejections now also DidNotAct: `import_exact` (invalid cid) and `publish` file (missing data) — both pre-effect (before the IPFS add), proven by `content::tests::content_write_request_shape_rejections_return_did_not_act`; the `storage_quota_exceeded` check correctly STAYS a structured error (capacity = transient, per the refined contract). `publish` request-shape rejections are now fully drained too: `unsupported_content_kind` and directory `files-must-be-array` also return `DidNotAct` (pre-effect, before the IPFS add; covered by the same test). Remaining drainable (noted, lower-value, deferred): only the HELPER-gated `import_exact` validations (`validate_import_exact_invocation`, `import_exact_payload_bytes`) — migrating those means changing shared helper contracts, a wider edit held for a dedicated pass. **The clearly-pre-effect, single-site request-shape rejections across all carrier-only providers (gossip, availability, content) are now DRAINED — the in-cloud BUG-4 frontier is effectively complete.** First-migration candidate `InspectProvider` was VERIFIED `W3b-turn` and is NOT a drop-in: its `send_raw` `Ok(error-status Value)` contract is relied on by BOTH transports (the carrier AND the gateway provider proxy `gateway_provider_proxy.rs:1399`) plus ~21 assertion sites in inspect tests, so emitting `Err(DidNotAct)` is a multi-caller refactor (update the gateway proxy inspect handling + re-decide the error contract on both transports + the tests), not a quick PoC. RECOMMENDATION: the first real migration should instead target a CARRIER-ONLY provider whose `send_raw` error shape no gateway path consumes, OR do InspectProvider as its own scoped chunk. Each migration needs the same per-op "provably no side effect" judgement (the audit is the gate, not a blanket sweep); BUG-5 (med) **CLOSED `W3b-turn`** — the carrier `request_capability` poll loop (sleep-then-check) dropped a grant landing between the last in-loop poll and loop exit, reporting a spurious timeout. Extracted `await_capability_decision` (poll the pending store, then ONE final read after the loop) + a `CapabilityDecision` enum; the carrier bridge now routes through it. Test-first + deterministic (no timing flake): `carrier_bridge::tests::await_capability_decision_catches_a_grant_after_the_loop` runs with `max_polls = 0` so ONLY the trailing read can find the grant (would time-out under the old code), plus a clean-timeout case. RESIDUAL **CLOSED `W3b-turn`**: the WASM **API** bridge's HTTP poll (`handle_remote_request`) had the analogous shape; now routed through a transport-agnostic `poll_then_final_read` (loop + ONE trailing read), so an HTTP grant landing after the last poll is no longer dropped. Tested deterministically WITHOUT a flaky HTTP mock: `carrier_bridge::tests::poll_then_final_read_catches_a_decision_after_the_loop` runs the helper with `max_polls = 0` (loop skipped) so only the trailing read can return the decision — the exact gap the old loop had; BUG-6 (low) **CLOSED `W3b-turn`** — carrier `MAX_LINE_BYTES` was checked AFTER unbounded `read_line`/`.lines()` (an untrusted guest could OOM the host with a newline-less line before the check ran). Fixed with a `take(MAX+1).read_until` bounded reader (`read_bounded_line` async + `read_bounded_line_sync`) that caps allocation DURING the read and drains to the next newline so the stream realigns; wired into ALL THREE bridges (the WASM API bridge previously had no bound at all). Test-first proof: `carrier_bridge::tests::read_bounded_line_*` (oversized rejected + realign, oversized-at-EOF, CRLF, sync twin) over in-memory pipes; BUG-7 (med) reap treats Carrier backend as unconditionally alive; BUG-8 (low) **CLOSED `W3b-turn`** — `next_cid` used an unchecked `*next += 1` (overflow/wrap) with no free-CID scan, so a wrapped counter could re-hand a CID a live VM still held. Replaced with `allocate_cid(from, in_use)`: floors the reserved low CIDs (0/1/2 → guests start at 3), skips any CID in the live `running` set, wraps the u32 space via `checked_add().unwrap_or(MIN_GUEST_CID)`, and fails closed (refuses the launch) if exhausted. Test-first: `supervisor::tests::allocate_cid_*` (reserved floor, skip-live, wrap-without-overflow, wrap-does-not-collide-with-a-live-VM, free-within-bound). Wave-2 structural: the audit group-commit rewrite is DONE (`S51`, above); AUD-4 plane-(a) remains. ## Enforced invariants (the inverse — already guaranteed, not gaps) @@ -73,6 +78,472 @@ for open work: - **Boot-critical sub-providers are pinned first-writer-wins** — `8b688fc`: `register_sub_provider` refuses (structural `Err`, checked under the write lock) to overwrite a still-live pinned slot (`encrypt`/`publish`/`media`/`key`/`decrypt`/`drm`/`rights`/`wallet`/`chain`), so a launched capsule declaring `provides: elastos://encrypt/*` cannot seize the CEK-escrow route (Principle 3/15); `unregister_sub_provider` frees the slot so a genuine restart re-mounts. Proven by `test_pinned_sub_provider_is_first_writer_wins`; non-pinned names keep last-write-wins. - **`request_act` inbox intake fails closed on an undeclared op (consent needs visibility)** — `d9bf5cc`: `create_inspect_action_request` rejects when the plan reports `data.valid != true` BEFORE persisting, so an operation the target authority never declared writes no pending record / no approvable Inbox row (it would otherwise prompt an approval with an empty gate preview). Proven by `gateway_tests::inspect::inspect_action_rejects_undeclared_operation_before_inbox` (+ the 6 restored inbox-approval regression tests). This is the fail-closed intake feeding the G3/G4 dispatch/approval loop. +## Mandate lifecycle (Sprint 3) — tracked latent gaps (guardian F1/F3 + red-team, 2026-07-04) + +The grant → revoke → prove loop shipped with these HONEST bounds: + +- **G-M1 CLOSED (Sprint 5).** `dispatch_standing_intent` consults BOTH the manager's individual + token-revocation store AND epoch validity (via the token epoch captured in the envelope at issue) + before the gate, and self-heals the envelope to revoked — so a backing token killed by ANY path + (individual revoke, `revoke_all`, or a key-rotation epoch advance) denies dispatch with the honest + `revoked` reason. Ratchets: `dispatch_denies_when_the_backing_token_is_dead_by_any_path`, + `dispatch_denies_after_an_epoch_advance`. + RESIDUAL (narrow, documented): a manager-revoke landing between the probe and the gate's envelope + read lets one in-flight act complete — the authoritative liveness check is not yet atomic inside + the gate. Single-request window; the act is still fully receipted. Closing it means giving the + pure gate manager access (a deeper refactor). +- **G-M2 CLOSED (Sprint 5).** Dispatch records a token-keyed `CapabilityUse` (success = a `Matched` + reconciliation, not merely gate-passed) alongside the intent-keyed records, so + `export_mandate_receipt_for_capability` carries every intent-channel act AND every denied attempt. + The use record is best-effort (like the validate path): a lost emit under-reports in the receipt, + but the intent-keyed declaration + reconciliation are already durable. Ratchet: + `dispatch_acts_under_the_mandate_and_the_receipt_carries_the_act`. +- **G-M3 (same-uid trust boundary, documented not defective).** The loopback control plane's + authority reduces to "can read the 0600 coords/attach-secret files" — i.e. the operator uid. Any + same-uid process inherits full mandate authority. This is the declared trust boundary of a + single-operator runtime; revisit if multi-tenant hosts land. +- **G-M4 (agent-key binding — DEFAULT-BOUND on the web surface + SURFACED, Sprint 20).** A mandate + MAY bind an authorized agent ed25519 key, and when set the gate requires the intent to be signed by + THAT key (`EnvelopeDenial::WrongAgent`), so the audit attribution is the real agent — proven by + `dispatch_binds_the_authorized_agent_key`. Sprint 20 promoted binding from optional to the DEFAULT + posture where it matters and made it VISIBLE: + (a) the SHELL grant surface (`gateway_mandates::mandate_issue`) now REQUIRES an agent key — an + unbound (capsule-string-only) mandate is refused server-side (BAD_REQUEST), not just discouraged in + the form, so the narrower posture holds even against an XSS in the frame (mirrors the Sprint-15 + admin refusal). Unbound mandates remain available on the CLI/consent-broker API for the trusted + operator (G-M3) — a deliberate operator choice, never a one-click web default. + (b) the mandate CARD now carries `agent_bound` + `agent_pubkey`, and the shell renders a + bound/unbound badge, so the operator can SEE the attribution strength of every mandate (P12), not + just trust it. Ratchets: `capability::tests::card_surfaces_agent_binding_and_api_still_allows_unbound` + (card honesty both ways + API-path unbound still allowed), `gateway_mandates::tests:: + issue_route_enforces_the_shared_guards` (web unbound + empty-key refused), + `issue_route_mints_a_live_mandate_in_the_shared_registry` (bound mandate mints + card shows it). + Council red-team F1 (HIGH, folded before ship): a WEAK (small-order / identity) ed25519 key parses + as a valid 32-byte "bound" key but a forged signature validates for it under any message — a + mandate bound to it would be forgeable by anyone (effectively unbound wearing a "bound" badge, + strictly worse than honest-unbound). Closed at BOTH layers: (i) `issue_mandate` now rejects a weak + key (`VerifyingKey::is_weak()`) at mint (BAD_REQUEST), so a bound mandate always means a real + single-agent binding; (ii) the signature gate uses `verify_strict` everywhere (`verify_b64_sig`), + rejecting small-order signer keys + non-canonical signatures at verification, not just at mint — + the security-correct default. Ratchets: `capability::tests::issue_refuses_a_weak_agent_key` (+ the + 44 intent tests confirm strict verification does not reject legitimate signatures). RESIDUAL: + full-strength attribution still rests on the trusted-core executor's honesty and the same-host + trust model; a DID-anchored agent identity (binding the agent key to a verifiable identity, not + just a raw key) is the deeper follow-up. + (c) **state-read binding — Sprint 25 council F2.** An UNBOUND mandate skips `WrongAgent`, so it is + gated only by token-id secrecy. Sprint 17's `state_put` exposed this as an INTEGRITY risk (anyone + with the token could overwrite the principal's state); Sprint 25's `state_get` extends it to + CONFIDENTIALITY (an existence + equality-guess ORACLE over the principal's stored value-hashes — + never a raw value disclosure, since the value is not surfaced, F1). CLOSED for the read: + `issue_mandate` now REFUSES an unbound mandate authorizing `runtime.state_get` (BAD_REQUEST) — a + state-read mandate must bind an agent key. Ratchet: + `capability::tests::unbound_state_get_mandate_is_refused_at_mint`. RESIDUAL (tracked, its own + sprint to avoid changing an accepted contract): `state_put`'s unbound INTEGRITY gap is unchanged — + a symmetric "require binding for `state_put`" would close it but retroactively narrows the + operator/CLI's accepted unbound-write posture; `runtime.notify` (unbound → inbox-spoof under a + capsule name) is the third of the same family. The principled endpoint is: every side-effecting or + state affordance requires agent binding. +- **G-M5 CLOSED (Sprint 14) — durable mandates: the registry AND the replay guard survive restart.** + The serve-path `StandingGrantService` is now snapshot-backed (`standing_grants.json` next to the + capability store; version-pinned, atomic temp+fsync+rename mirroring `CapabilityStore`), so a + granted mandate is still LIVE after a reboot, a revoked one STAYS dead (never crash-revived), and + a dispatched `intent_id` is still refused (the replay guard persists). Ordering is durable-before- + visible with rollback on EVERY mutation (issue / revoke / revoke_all / record_fresh_intent): a + write that cannot be persisted is rolled back in memory and the error SURFACES — the issue handler + refuses to mint (500, "not issued"), dispatch refuses the intent when the replay guard or the + G-M1 heal cannot be recorded, and the mass kill reports failure rather than a clean success whose + envelopes could resurrect as "Live" cards. Boot is fail-closed: a present-but-corrupt (or wrong- + version) snapshot REFUSES to start (a skipped record could resurrect a revoked mandate or reopen + a replay window); a missing file is a clean first boot. POWER-LOSS durable, not just + process-restart durable (red-team F1): the snapshot write fsyncs the temp file AND (unix) the + parent directory after the rename — without the directory fsync a power cut could revert the + rename to the OLD snapshot, and for the replay guard that revert IS a replay window (a captured + signed intent acting twice; unlike a reverted revoke, which the durable token-revocation check + still backstops at dispatch, a lost seen-intent has no second line). Same-disk custody caveat as + the audit log's head-anchor: this defends against loss/corruption, not a root attacker who + already owns the key material — and honestly bounded (red-team F2): the strict parse + + `deny_unknown_fields` catch STRUCTURAL damage and unknown-field skew, but a semantically-valid + same-disk edit that DROPS an `Option` field (deleting `agent_pubkey` unbinds an agent-bound + mandate — serde defaults missing `Option`s to `None`) is inside that caveat; making well-formed + edits detectable needs a keyed MAC (roadmap, same class as head-anchor co-signing). The + carrier_bridge's own registry stays memory-only by design (separate instance; two services over + one path would clobber snapshots). **G-M5 residual CLOSED (Sprint 19) — the replay guard is now + time-WINDOWED and BOUNDED, not monotonic.** A `declared_at` freshness window + (`check_intent_freshness`: `[now - MAX_INTENT_AGE_SECS(3600), now + MAX_CLOCK_SKEW_SECS(300)]`) is + enforced at dispatch AFTER authenticity and BEFORE the replay guard, so a stale or future-dated + declaration is refused (400) without burning an id — a captured intent EXPIRES rather than being + replayable indefinitely. The seen-set now stores each id's `declared_at` and self-compacts against + the retention window on every write (dropping ids that can no longer pass freshness, so forgetting + opens no replay), making it bounded to ~one window of intents instead of growing forever. The + snapshot moved to v2 (`SeenIntentRecord{id, declared_at}`) with a fail-closed-preserving v1 + MIGRATION (legacy bare ids re-stamped at load time so they age out one full window — never a + replay window; a v1 file is upgraded, never refused). BACKWARD-CLOCK replay hole CLOSED by an + ANTI-READMIT WATERMARK (red-team Finding 1, folded before ship): compaction forgets aged ids to + stay bounded, which alone would let a captured intent be REPLAYED after a two-step clock move + (evicted while the clock was high, then re-POSTed after a backward step back into its freshness + window). The store now keeps a persisted `max_evicted_declared_at` — the highest `declared_at` + ever compacted out — and refuses any intent with `declared_at <= max_evicted` as a replay. That is + monotonic non-decreasing and clock-DIRECTION-INDEPENDENT, so an evicted id can never be readmitted + regardless of NTP steps / VM resume / manual clock changes, and it survives restart (persisted in + the v2 snapshot). Residual CLOCK-TRUST caveat (guardian S2): the freshness window still ages + against the host `SystemTime::now()` (same custody class as the same-disk snapshot caveat), but a + bad clock now fails CLOSED in BOTH directions — the watermark stops replay under ANY clock, and a + backward jump can at worst spuriously REJECT valid intents (availability, never a double-act). The + `RETENTION = age + skew` margin remains load-bearing under a monotonic clock; the watermark is the + belt to that suspender under a non-monotonic one. Ratchets: + `intent::tests::{persistent_store_survives_reopen_live_dead_and_replay, + persistent_store_refuses_corrupt_state_at_boot, persist_failure_rolls_back_and_surfaces, + freshness_window_rejects_stale_and_future_dated, + seen_set_compacts_aged_ids_but_still_catches_in_window_replay, + v1_snapshot_migrates_preserving_mandates_and_replay_guard, backward_clock_step_cannot_readmit_an_evicted_intent, evicted_watermark_persists_across_restart, persist_failure_keeps_the_watermark_so_an_evicted_id_cannot_replay}` + + `capability::tests::{mandates_survive_restart_over_the_handlers, + dispatch_rejects_stale_and_future_dated_intents}`. +- **G-M6 — the reconciliation seam is closed; ONE real affordance wired (honest).** Dispatch + invokes a real [`IntentExecutor`] (`intent_executor.rs`) INSIDE the gate's act closure (so a + denied/revoked intent never executes) and mints the affordance receipt from what the executor + REPORTS, never from the declaration. The over-claim is retired: a method with no executor (or one + that declines) is `Undelivered` — outcome `authorized_not_performed`, receipt use `success=false` — + instead of a fabricated match; an executor that reports a field other than declared is `Diverged`; + only a faithful performance is `Matched` (`performed`, `success=true`). The PRODUCTION executor set + registers exactly ONE method today (`runtime.audit_verify`, below) — every other method is + `authorized_not_performed`; a no-op that echoed the declaration is deliberately NOT shipped (it + would re-introduce a `success=true` "write" for a method that performed no write). Ratchets: + `dispatch_acts_under_the_mandate_and_the_receipt_carries_the_act` (faithful → performed), + `dispatch_reconciles_unperformed_and_diverged_acts_honestly` (unwired method → Undelivered; a + shifting executor → Diverged; both `success=false`). + BOUNDS (documented, not defects): (a) the seam is independent for the Undelivered/Diverged legs; a + faithful executor is Matched-by-construction, so `Matched` proves report-fidelity (report == + declaration), NOT reality (effect == declaration) — that rests on the trusted-core executor's + truthfulness. (b) Side-effecting affordances (mail/payment/storage) are registered as wired, each + behind its own capability gate, and their executors MUST hash ACTUAL inputs and report the action + they REALLY did. + FIRST REAL AFFORDANCE WIRED (Sprint 7): `runtime.audit_verify` — a genuine, SIDE-EFFECT-FREE read + that re-verifies the runtime's own tamper-evident chain (hash links + ed25519 sigs) and + `Performed`s iff it actually verifies. It reports the fields it TRULY acted on — resource = + `elastos://runtime/audit-chain` (the whole chain, NOT the declared resource), action = `read`, + input_hash = empty (no arguments) — so a mandate mis-scoped to another resource, or a non-read + action, reconciles `Diverged` rather than a misleading `Matched` + (`dispatch_really_performs_the_wired_audit_verify_read`, `audit_verify_under_a_misscoped_mandate_diverges`). + It DECLINES (⇒ Undelivered) when the log is unsigned/memory-only (`vk` = None): `verify_chain(None)` + is a hash-only walk over a public algorithm, so a `performed` must mean SIGNATURE-verified, not + merely self-consistent (`audit_verify_declines_on_a_memory_only_chain`). So `performed` is now + LITERAL for one method — the outcome tracks real signed-chain state, not the declaration. + RESIDUALS (documented, not defects): `verify_chain` re-reads the whole log per call (O(chain) — a + deliberate, gated, on-demand op; DoS-bounded by the shell-only + agent-key-bound + replay-guarded + mandate, medium); the verified count is observed but not surfaced in the reconciliation fields + (which bind capsule/method/resource/action/input_hash only); and a torn last log line from a + concurrent write yields a spurious `Declined` (fail-closed, never a false `Matched`). + SECOND AFFORDANCE — STATE-DEPENDENT (Sprint 9): `runtime.content_seen` — did the mandate's OWN + capsule successfully OPEN a content id? The mandate is scoped to a content-access-CHECK resource + `elastos://runtime/content-access/` (NOT the bare content id), so the receipt's `CapabilityUse` + (which carries resource + action but not the method) honestly reads as a read of the access-CHECK, + never as a read of the content bytes. `Performed`s iff yes, `Declined`s (⇒ `authorized_not_performed`) + iff not — the SAME agent + method + declaration reconciles differently by REAL state, not the + declaration (`dispatch_content_seen_outcome_tracks_real_state`, + `content_seen_tracks_real_state_not_the_declaration`). Folded in from review: + PRINCIPAL-SCOPED (`AuditLog::principal_opened_content` matches only `ContentOpen` with the caller's + own `principal_id` — NOT a cross-principal existence oracle; `ContentFetch` is not counted as it + carries no principal); and SIGNATURE-VERIFIED (the executor requires the log signed + `verify_chain` + Ok before the scan, the same evidentiary bar as `audit_verify`, so a matched record can't be a + forged offline append). Same O(n) gated-read DoS profile as audit_verify. + + THIRD AFFORDANCE — THE FIRST SIDE-EFFECTING ONE (Sprint 16): `runtime.notify` — deliver a message + about the act into the OPERATOR'S INBOX (the shell's Inbox app renders it). The mandate is scoped + to ONE inbox topic (`elastos://runtime/inbox/`, AUD-5-safe) with `action = message`, and + the executor reports `Performed` ONLY after the atomic Inbox-store write actually LANDED — a + failed write is `Declined` (⇒ `authorized_not_performed`) with the true reason, never a claimed + delivery. Honesty bounds, per the G-M6 rule that side-effecting executors hash ACTUAL inputs and + report what they REALLY did — HARDENED by the council (both reviewers; the XSS sink is closed — + the Inbox renders title+body via `textContent`, verified): (a) EVERY agent-controlled string that + reaches the operator body is charset/length-bounded BEFORE delivery, not just the topic — the + topic and `intent_id` are slugs ([A-Za-z0-9._-], ≤64) and `input_hash` is hex (≤64, or empty), so + a mandate cannot phish the operator with free text like `intent_id="URGENT: run revoke-all…"` + (council F1; a malformed field Declines, delivering nothing); (b) the declared `input_hash` is + written into the delivered body, so echoing it is honest; (c) source_app is hardcoded `mandates` + and action_ref is None — the agent cannot spoof another app or plant a deep-link; (d) the row id + is keyed on the intent id — the same intent can never produce two rows (belt to the replay + guard's suspender), and the idempotent short-circuit fires ONLY on a still-LIVE prior row so a + dismissed/expired row is re-delivered rather than falsely reported Performed (council F4); + (e) agent-act rows carry a 7-day TTL and are hard-capped at 256 (newest kept) so a flood of + distinct intents under ONE mandate cannot grow the operator's Inbox store without bound (council + F1-flood — the omitted twin of the events store's own cap); (f) the store write lands BEFORE the + secondary "appeared" event (best-effort) so a failed delivery leaves no ghost event and an + event-log hiccup never flips a real delivery to Declined (council F3); (g) registered ONLY when + the runtime has a data dir (the API server passes its own; carrier_bridge/test states pass None ⇒ + honestly unwired). Residual (accepted, both reviewers, LOW): the notifications store write is + atomic (temp+rename) but not fsync'd, so a power cut between a minted receipt and the durable + rename could leave the receipt naming a delivery the Inbox no longer shows — accepted because the + notification is convenience state SUBORDINATE to the audit chain (the accountability record is the + receipt's `CapabilityUse`, which rides the fsync'd signed chain), and the direction is a benign + under-show, not a fabricated delivery. Ratchets: + `intent_executor::tests::{notify_delivers_a_real_inbox_notification_and_reports_message, + notify_declines_bad_scopes_and_delivers_nothing, + notify_declines_operator_unsafe_intent_fields_and_delivers_nothing, + notify_flood_is_bounded_by_the_agent_act_cap, notify_is_unwired_without_a_data_dir, + notify_declines_when_the_store_write_fails}` + the full loop + `capability::tests::dispatch_notify_delivers_to_the_inbox_and_the_receipt_carries_it` + (grant → dispatch → REAL delivery visible to the Inbox app → revoke → same act denied with + nothing delivered → the portable receipt carries the delivery AND the denial, verified off-box). + + FOURTH AFFORDANCE — THE SECOND SIDE-EFFECTING ONE (Sprint 17): `runtime.state_put` — write a + durable, readable-back agent-state KEY (`elastos://runtime/store/`, `action = write`), + proving the council-hardened side-effecting pattern generalizes from a one-shot notification to + real mutable data. Honesty carried over verbatim from the notify hardening: (a) PRINCIPAL-SCOPED — + an entry's identity is `(capsule, key)` where `capsule` is gate-bound to the mandate, so one agent + can never read or overwrite another's key (the same scoping `content_seen` uses); (b) the stored + value is the declaration's `input_hash` COMMITMENT, NOT a free-text payload — the intent carries + no bytes, only their hash, so the store records exactly what the mandate receipt already binds + (nothing an agent writes can smuggle content the signature does not cover); (c) the key is a slug + ([A-Za-z0-9._-], ≤64) and the value hex (≤64, or empty), bounded BEFORE the write; (d) last-write- + wins with a monotonic per-key `version` (attributed history depth without keeping every revision); + (e) a per-capsule key cap (256, oldest of THAT capsule evicted — never another's) bounds a flood; + (f) `Performed` iff the atomic write LANDED, else `Declined` with the true reason; (g) registered + ONLY with a data dir (carrier/tests pass None ⇒ honestly unwired). The write is a REAL durable + effect — the entry lands in `agent_state.json` and `agent_store::get_agent_state` reads it back + (principal-scoped) — so the effect is independently observable, not just claimed. The operator + READ SURFACE landed (Sprint 18, closing the red-team F3 follow-up): `GET + /api/apps/mandates/agent-state` (home-token gated) + an "Agent state" panel in the Mandates shell + app show what every agent has written under its mandate — capsule, key, the commitment hash + (labelled as such, never content), version, attributing mandate, time. It is OPERATOR-scoped + (`agent_store::list_agent_state` spans all principals) because the caller is the shell / grant + root that already sees every mandate — NOT an agent path (agents stay isolated by the + per-principal `get_agent_state`; nothing on a trusted decision path reads the store, so an agent + writing its own value still cannot escalate). The panel renders every cell via `textContent` (the + council-hardened XSS discipline), so an agent's key/value/attribution can carry no markup. Read + ratchets: `gateway_mandates::tests::{agent_state_route_requires_home_launch_token, + agent_state_route_reflects_the_store_across_principals}`. Scale watch-item (red-team F2, SUSPECTED + low, same shape as the notify inbox store): `put_agent_state` rewrites the whole store per write, + O(total entries) — bounded because capsule count is operator-gated (agents can't mint mandates) + and every field is length-bounded; per-capsule sharded files if it ever matters. Ratchets: + `agent_store::tests::{put_then_get_is_principal_scoped_and_versions_on_overwrite, + per_capsule_key_cap_evicts_only_that_capsule}` + + `intent_executor::tests::{state_put_writes_durable_readable_state_and_reports_write, + state_put_declines_bad_scopes_and_writes_nothing, state_put_is_unwired_without_a_data_dir, + state_put_declines_when_the_store_write_fails}` + the full loop + `capability::tests::dispatch_state_put_writes_durable_state_and_revoke_stops_it` (grant → write → + readback → overwrite/version → revoke → same write denied, value unchanged → receipt carries both + writes AND the denial, verified off-box). Residual (accepted, same class as notify's, LOW): the + agent-state store write is atomic (temp+rename) but not fsync'd — a crash-revert could drop a + write the receipt already recorded, a benign under-show (the accountability record is the receipt + on the fsync'd audit chain, not this convenience store); both side-effecting stores share the + accepted notify baseline (raise both to the standing-grant registry's fsync bar together if ever + promoted). Also carried over from the notify hardening (council pre-fold): the PERSISTED + `intent_id` is bounded to a slug like the key, so no unbounded/free-form field bloats durable + state or (once a read-back surface lands) reaches a human — ratchet + `intent_executor::tests::state_put_declines_an_unbounded_intent_id`, and the cap explicitly never + evicts the just-written key (`per_capsule_key_cap_evicts_only_that_capsule` asserts the last write + survives its own eviction under same-second timestamps). + +- **OPERATOR SURFACE — the mandate list ships as a launchable ElastOS shell app, on LIVE data + (Sprints 10→12).** The operator sees (and proves) their agents' autonomy through the `mandates` + capsule (`capsules/mandates/`, `role:app` + `entrypoint:index.html`) — auto-listed by the home + shell and opened as an ordinary app window, NOT a bespoke route and NOT a new shell (ElastOS is the + workbench; Flint's ADE shell is the future destination that inherits this). Sprint 12 wired it to + LIVE runtime data: a read-only sub-router (`api/gateway_mandates.rs`) on the home gateway serves + `GET /api/apps/mandates/standing-grants` (the mandate list + audit signer key) and + `GET /api/apps/mandates/mandate/:token_id/receipt` (the portable per-mandate receipt), BOTH gated by + the same `require_home_launch_token(..,"mandates")` home-launch token every shell app uses (a token + minted for a different capsule is rejected — the app binding is enforced), and BOTH strictly + read-only (no mint, no mutation). It reads the SAME `StandingGrantService` registry the API server + issues mandates into (ONE handle hoisted into `ServerInfrastructure`, threaded to both the API + server and — via the supervisor — the gateway), so the shell never shows stale data; the merge only + happens when both the registry and the capability manager are present (control-plane gateway = + no mandate routes, fail-closed). Both surfaces (API server + gateway app) render the card through + ONE shared projection `handlers::capability::mandate_cards`, so the liveness invariant cannot drift + between them: the `active` bit consults ALL three kill paths — envelope flag, individual token + revocation, AND `is_epoch_valid` (a key-rotation / `revoke_all` epoch advance) — fail-closed + inactive on an unparseable id, so a revoked/expired/epoch-killed mandate NEVER renders "Live" (P12). + (Folding the epoch check into the LIST view — not just the dispatch path — closed a guardian+red-team + finding that both list surfaces previously over-reported epoch-killed mandates as Live.) The receipt + path reports honest absence as `404`, never a fabricated sample under a real token id. The capsule + reads its live data ONLY when launched in-shell (the signed `home_token` rides in the launch URL → + `x-elastos-home-token` header); opened standalone it falls back to an explicitly LABELLED "sample", + and an in-shell fetch failure shows an honest "unavailable" banner, never sample data under the live + view. THE KILL SWITCH (Sprint 13): `POST + /api/apps/mandates/standing-grants/revoke` — same home-token gate, delegating to the SAME shared + kill path the API server uses (`handlers::capability::revoke_mandate`: signed `CapabilityRevoke` + durably attested BEFORE the envelope dies; an unattestable revoke ABORTS loudly, per AUD-3), so the + fail-closed revoke order cannot drift between surfaces. Revoke only REMOVES authority — the worst a + stolen mandates launch token does on this surface is kill an agent's autonomy early (fail-safe + direction). In the drawer it is two-step (arm → confirm), shown only in-shell on a LIVE mandate; + a transport failure is reported with honest uncertainty (the list is refreshed and the card state + is authoritative — the runtime attests before replying). GRANT FROM THE SHELL (Sprint 15): `POST + /api/apps/mandates/standing-grants/issue` — the full lifecycle (see/grant/act/stop/prove) now + lives in the app. Issue is authority-GRANTING, so its trust argument is explicit: the home-launch + token is minted by the runtime's own key only when the SHELL launches the app, and the shell is + already the runtime's grant root (the API's issue endpoint sits behind the consent-broker gate + for the same reason; G-M3) — the gateway surface adds NO new authority tier, and delegates to the + ONE shared mint path (`handlers::capability::issue_mandate`) with every fail-closed guard intact + (action whitelist, non-empty methods, AUD-5 overbroad-wildcard refusal, agent-key validation, + durable-before-visible issuance). The form exists only in-shell and repaints the list FROM the + server — a granted card is what the runtime recorded, never a locally-fabricated row. Council + hardening (P16 defense-in-depth, since the granting verb now lives in a web iframe holding the + in-URL home_token): the capsule ships a strict CSP (`default-src 'none'`, same-origin + `connect-src`, `base-uri/form-action 'none'`) so no injected remote script can mint or exfiltrate + the token; and the gateway issue route REFUSES `admin` server-side (case-insensitive) — admin + mandates are minted from the CLI/consent-broker API only, so the web surface is deliberately + NARROWER than the raw API even against an XSS in the frame. Ratchets: + `gateway_mandates::tests::{list_route_requires_home_launch_token, + list_route_reflects_the_shared_registry, list_route_marks_epoch_killed_mandate_dead, + receipt_route_requires_home_launch_token, receipt_route_reports_absence_as_404, + revoke_route_requires_home_launch_token_and_kills_nothing, + revoke_route_kills_the_mandate_and_is_idempotent, revoke_route_rejects_malformed_id, + issue_route_requires_home_launch_token_and_mints_nothing, + issue_route_mints_a_live_mandate_in_the_shared_registry, issue_route_enforces_the_shared_guards + (incl. server-side admin refusal)}` + + `browser_capsules::mandates_ships_as_a_launchable_browser_app`. + +- **G-M7 (Sprint 15 council — the mint's OPERATIONAL residue; bounded to an authenticated shell-tier + caller, NOT a boundary break).** Both reviewers confirmed the issue route adds NO new authority + tier (only the runtime-signed, non-delegatable, `app=="mandates"` home-launch token — obtainable + only via the Home-shell-gated `home_launch` — reaches it; CSRF is closed: header-only token, no + permissive gateway CORS; the AUD-5 guard is exact and shared). Residuals, all reachable only WITH + a genuine shell token (the trusted operator, G-M3): + (a) **Rate/flood bounding — DISPATCH now rate-budgeted + existence-gated (Sprint 21); mint + retention still open.** The sharpest, agent-facing half is CLOSED: each mandate now has a + per-mandate DISPATCH RATE budget (`MANDATE_DISPATCH_LIMIT` acts per `MANDATE_DISPATCH_WINDOW_SECS`, + default 60/60s). **Council fix (this is what makes the claim true):** the `standing_grant_id` is + attacker-chosen (self-signed into the declaration; bound to a real mandate only later, at the + gate), so a per-`grant_id` budget alone would NOT stop a flood of DISTINCT fake grant_ids — each + would pass the budget as a new key and still pay the durable replay-guard fsync, which runs before + the grant is ever looked up (guardian F1 / red-team F1+F2, both CONFIRMED). The handler therefore + now resolves grant EXISTENCE in memory FIRST — after authenticity + freshness, before the rate + budget and before the durable write — and refuses an unknown grant_id cheaply (`denied` / + `no_standing_grant`, no fsync, no rate entry). Only real, operator-issued grant_ids (a + registry-bounded set) are ever counted or durably recorded, so: a flooder rotating fake grant_ids + is turned away before any durable cost, and a mandate-holder flooding its OWN real grant is refused + `429` before the fsync once over budget (Sprint 19 bounded the replay SET; this bounds the RATE). + The rate map is HARD-CAPPED (`DISPATCH_RATE_SOFT_CAP`): elapsed windows are pruned, and at capacity + a new key is refused — so even a same-window distinct-key flood cannot grow it (an already-seen key + is always still counted, so a real mandate is never shed). The limiter is in-memory (a restart + refills the budget — safe/generous, and the agent cannot restart the runtime). Ratchets: + `intent::tests::{dispatch_rate_budget_bounds_a_mandate_then_resets_next_window, + dispatch_rate_map_is_bounded_against_distinct_grant_spam}` + + `capability::tests::dispatch_over_rate_budget_is_refused_429`. RESIDUALS: (i) **charge-on-attempt + — CLOSED for the AGENT surface (Sprint 26).** On the shell route the budget is charged for a + well-formed fresh intent naming a REAL grant even before the gate's agent-key check, so someone who + could name a victim's grant_id could burn its window budget (worse the tighter the S22 dial). That + route is operator-only (the operator locking out its own mandate is not an attack), so it stays as + is. The new AGENT-FACING route (`/api/agent/dispatch`, Sprint 26) authenticates the caller as the + mandate holder — it REQUIRES a bound mandate + `intent.signer == agent_pubkey` BEFORE delegating to + the pipeline, so a wrong-key intent never reaches the rate charge (charge-on-authorized). An + attacker naming a victim's grant is refused 403 and charges NOTHING. Ratchet: + `capability::tests::agent_dispatch_charge_on_authorized_no_victim_lockout`. PRECISE SCOPE + (Sprint 26 council): "closed" is against the GRANT-ID-KNOWLEDGE attacker (who only learns a + victim's grant_id). It is NOT closed against a stronger attacker who CAPTURES a fresh SIGNED intent + from the bound agent — that intent passes the binding, so replaying it first on the agent route + spends one budget unit and burns its intent_id (the agent's own retry then 409s). This is + rate-bounded, requires signed-material exfiltration, and pre-exists on the shell route; the deeper + fix is charge-only-on-gate-pass. Also inherent: a legit key-holder dispatching against its OWN + revoked/out-of-envelope mandate passes the wrapper (a revoked envelope is still returned) and + charges its budget before the gate's honest `revoked`/`wrong_*` denial — self-inflicted, + budget-bounded, and it buys the true denial reason. Anti-anonymous-DoS on the route rests on + `auth_middleware` + `rate_limit_middleware` (per session); the residual amplification is + session-issuance economics (pre-existing, unchanged by S26 — an attacker minting N sessions gets N + request buckets, but the per-mandate budget is untouched). + (ii) **fixed-window boundary** allows up to ~2× the limit across a window edge (60 at the tail of + W + 60 at the head of W+1); acceptable for a flood bound (still O(1)/window, ~1/s average), noted + not silent. RETENTION now SHIPPED (Sprint 23 — closes the DEAD-accumulation half of G-M7): the + working registry's DEAD growth is bounded on BOTH axes. Time: a DEAD grant (revoked past + `revoked_at`, or expired past `expires_at`) is pruned `GRANT_RETENTION_SECS` (30 days) after death. + Space: a `REGISTRY_HARD_CAP` backstop evicts the OLDEST-dead grants first if still over cap, and + NEVER a live one (a live set over cap is operator-real authority, bounded by real issuance — never + shed to satisfy a bound). The prune runs at the growth point (`issue`, exempting the just-issued + grant) and on boot (to shrink a file grown under an older binary), durable-before-visible with + rollback on a persist failure. The audit CHAIN keeps every grant/revoke/use independently (the + receipt is the permanent record; the registry is only the working set) — pruning erases nothing + provable. `revoked_at` is a `serde(default)` field (a missing value = "never TIME-prune" = RETAIN, + the fail-safe direction for the clock stage), so it needs no version bump. Ratchets: + `intent::tests::{retention_prune_ages_out_dead_grants_but_keeps_live_and_recent, + retention_hard_cap_evicts_oldest_dead_never_live, retention_never_sheds_a_live_set_over_cap, + revoke_stamps_revoked_at_roundtrips_and_issue_prunes_expired}`. HONEST BOUNDS (Sprint 23 council): + (1) LIVE growth is NOT bounded — a shell-token holder minting no-TTL live mandates grows the + registry without limit, BY DESIGN (a live mandate is real G-M3 authority, never shed); only DEAD + accumulation is reclaimed. (2) The "chain is the permanent record" holds for MANDATES **under the + durable audit log** — CLOSED Sprint 24 (conditional): `CapabilityManager::grant_durable` emits the + signed durable `CapabilityGrant` BEFORE returning the token (emit-before-issue, mirroring + `revoke`), and `issue_mandate` uses it — so a mandate whose grant event cannot be recorded is never + issued (500, no token), and a retention-pruned mandate can never have existed without a provable + grant on the chain. Proven by + `capability::manager::tests::grant_durable_fails_closed_when_audit_write_fails` + the existing + issue→`export_mandate_receipt_for_capability` receipt tests (now routed through the fail-closed + mint). DURABILITY BOUND (council S24 F1, the conditional): `grant_durable` is only as durable as + the audit log's backing. With the file-backed log (the EU-AI-Act custody mode, + `ELASTOS_AUDIT_LOG_PATH`) the grant is fsync'd before issue — fully closed. With the DEFAULT + memory-only log `emit` returns `Ok` without a disk write, while the standing registry IS persisted, + so a restart would restore the mandate without its grant record — the F1 gap via the audit door. + `issue_mandate` now WARNs loudly when minting into a memory-only log (a hard refusal would break the + legitimate ephemeral/dev mode); the fix for that mode is to run the durable audit. REVERSE-FAILURE + HONESTY (council S24 F2): if the grant lands but `issue_from_token` then fails (registry persist + error), `issue_mandate` emits a compensating best-effort `CapabilityRevoke` so the chain reads + "granted, then aborted" rather than an orphan grant a verifier would read as a live, never-revoked + mandate. RESIDUAL: the GENERIC `grant()` (non-mandate ephemeral tokens, not in the standing registry + and not retention-pruned) keeps best-effort audit by design — its ~79 call sites across unrelated + subsystems are out of scope for the mandate provability contract; converting them is the G8b + hot-path group-commit initiative, not this. (3) The 30-day operator-visibility + promise is conditional: under cap pressure (>4096 live+dead) recently-dead grants can be evicted + inside the window; the chain still has them. (4) Time-death is wall-clock: a >30-day FORWARD clock + excursion could permanently prune a live-but-recently-expiring mandate — a bound shared with expiry + itself (a clock-jumped mandate already denies), not cleanly clampable without a trusted external + clock. (5) Prunes emit no audit event: time-prunes are reconstructible from the chain (grant/revoke + times + the public constant), hard-cap evictions are not — noted for forensics, nothing provable is + lost. STILL OPEN (operator-gated, lower priority): the gateway ISSUE/REVOKE routes carry no + request-RATE limiter — a shell-token holder can still burst issue/revoke calls (registry SIZE is + bounded, the request rate is not). FIX (deferred): a per-token limiter on the gateway mutation + routes. SHIPPED (Sprint 22): per-mandate-CONFIGURABLE dispatch budgets — `dispatch_limit` is a + first-class grant property (registry state, same trust level as agent-binding — not signed into + the token or the receipt), set at mint (API + shell form; the CLI does not set it yet — a known + follow-up, so the claim is scoped to API+form). The mint refuses `0` and anything over + `MANDATE_DISPATCH_LIMIT_MAX` (3600/window): 0 would mint a mandate that renders Live yet denies + every act, and an unclamped limit would linearly uncap the fsync-flood bound the budget exists to + enforce (council red-team F2 / guardian F3) — a footgun stop, not an authority boundary (a + grant-root operator can already raise aggregate rate by minting more mandates). Enforced from the + registry via ONE resolver (`dispatch_limit_for`) shared with the over-budget 429 message, so the + number the gate enforces and the number it reports can never diverge (council F1); no caller or + intent field can influence it; a tampered zero denies every act, fail-closed. The invariant is + re-checked at the service layer (`issue_from_token`), not only the HTTP boundary (council F3/F7), + so a future direct caller can't store an out-of-range budget. Persisted in the v3 registry + snapshot: v1/v2 files migrate to `None` (= the global default they were enforced under — neither + widened nor tightened); a v3 envelope MISSING the key is refused, so an ACCIDENTAL key-drop / + boot-repair cannot silently reset a tightened budget. HONEST BOUND (council F4): this does NOT + defend against a same-disk attacker rewriting the whole unsigned file — an explicit + `"dispatch_limit": null` or a version-downgrade to v1/v2 still widens; that is the same same-disk + caveat the snapshot carries throughout (closing it needs the keyed-MAC roadmap item). Surfaced on + the mandate card as the ENFORCED number with a `custom` marker (P12: the card shows what the gate + does, via the same resolver). Ratchets: + `intent::tests::{per_mandate_dispatch_limit_overrides_the_default, + v2_snapshot_migrates_dispatch_limit_and_v3_roundtrips_it, + issue_from_token_rejects_out_of_range_dispatch_limit}` + + `capability::tests::mandate_minted_with_its_own_rate_budget_enforces_and_surfaces_it` (which now + also asserts the over-budget 429 reports the mandate's OWN resolved limit, not the default — F1). + (b) **Unbound + arbitrary-`capsule` is now a one-click grant (red-team F2; the UI default is + "unbound").** `capsule` is a free string (unvalidated) and an unbound mandate (`agent_pubkey` + None) enforces capsule-STRING-only — any self-signed key declaring that string acts under it + (G-M4). The mint TIER is unchanged (the shell could always do this via the API), but the form + makes `capsule:"system"`-attributed, agent-unbound authority a defaulted one click. NOT fixed by + a capsule allow-list ON PURPOSE: prior council reasoning (G-CIE) rejected trust-anchoring on a + spoofable capsule NAME; the principled fix is role-based capability tiering (a `CapsuleRole::System` + plumbed into the grant point) applied uniformly — a separate FUTURE initiative, not a Sprint-15 + wedge. Interim mitigations already shipped: the web form is narrower than the API (admin refused + server-side) and CSP-locked. UPDATE (Sprint 20): the web form now REQUIRES an agent key (G-M4 + default-bound), so a one-click unbound broad grant is no longer possible from the shell. + (c) **Proof-unbound local-mode token can now MINT (red-team F4, extends G-AUTH-LOCAL).** Under the + accepted operator-key-on-disk local posture a proof-unbound `mandates` token skips the live- + session recheck; it could previously read/revoke, and now also issue. Same operator-authority + root (the on-disk key already mints via the CLI), but note the fail-safe asymmetry the shell app + leans on — revoke only removes authority — does NOT hold for issue. Decide before a multi-tenant + gateway (same trigger as the G-AUTH-LOCAL decision). + (d) FIXED here: `SecureTimestamp::after_secs` now saturates (red-team F5) — a `ttl_secs` near + `u64::MAX` no longer debug-panics / release-wraps-to-the-past. + +Closed at review time (Sprint 3, before merge): the revoke id-casing desync (UPPERCASE hex +revoked the token but missed the lowercase-keyed envelope — now canonicalized + regression test +`revoke_with_uppercase_id_still_kills_the_standing_envelope`), and non-durable revocation +enforcement (production `CapabilityStore` now built `with_persistence`, so revocations + epoch +survive restart; fail-closed at boot if persistence is unavailable). Sprint 5 also added +`deny_unknown_fields` to `IntentDeclarationV1` and the `is_overbroad_grant_resource` guard at +`issue_standing_grant` (defense-in-depth, mirroring `grant_request`). + ## How to use this file - A new gap → add a row + an `#[ignore]`d ratchet test (or note "pending scaffold" if no API exists yet). - Closing a gap → wire it, delete the `#[ignore]`, confirm the test is green, move the row to a "Closed" section (or delete it — this is memory, not an archive). diff --git a/docs/LIVE_BUY_RUNBOOK.md b/docs/LIVE_BUY_RUNBOOK.md new file mode 100644 index 00000000..cda5d06c --- /dev/null +++ b/docs/LIVE_BUY_RUNBOOK.md @@ -0,0 +1,96 @@ +# Live DRM buy — operator runbook (the live-money last mile) + +This is the **operator-driven** procedure for exercising a real on-chain DRM buy end to end +(Grant → Act → Prove) against a live EVM testnet. It is deliberately NOT part of the CI gate: the +gate injects `DrmResolver`/`DrmSettler`/`DrmConfirmer` mocks and never touches a network or a funded +wallet (a sandbox has neither). Everything the gate *can* prove about this path — the money +direction, the price gate, confirmation-aware settlement, the rail discriminator, the deadline +discipline — is already proven by the ratchets named in `KNOWN_GAPS.md` (MKT-DRM). This runbook is +the last mile the gate cannot run for you: a real dollar (of testnet value) moving under a mandate. + +> **Safety.** Run this on a **testnet** (e.g. Base Sepolia) with a **throwaway funded wallet** first. +> The managed-signing path (`ELASTOS_DDRM_BUY_SIGN=wallet`) is a `dev-modes` build only — a release +> build never self-signs; it hands back the unsigned tx for an external wallet (SCOPE.md hard-gate). + +## 0. Prerequisites + +- A `dev-modes` build of the gateway: `cargo build -p elastos-server --features dev-modes`. +- Built capsules on `PATH` (or pointed at by env below): + - `cargo build --manifest-path capsules/chain-provider/Cargo.toml` + - `cargo build --manifest-path capsules/wallet-provider/Cargo.toml` +- A funded testnet account for the **managed** wallet (its address is minted on first use — see step 2; + fund THAT address), and a deployed ACCESS_TOKEN listing (operative + tokenId + an active seller). + +## 1. Environment (the money contract) + +| Variable | Meaning | +|---|---| +| `ELASTOS_DDRM_RIGHTS=chain` | The LIVE rights + buy path (not `dev`/`chain-mock`). | +| `ELASTOS_DDRM_BUY_SIGN=wallet` | Managed-account signing (dev-modes only). Omit ⇒ unsigned-tx-for-external-wallet. | +| `ELASTOS_CHAIN_PROVIDER_BIN` | The real chain-provider binary (RPC-backed). | +| `ELASTOS_WALLET_PROVIDER_BIN` | The wallet-provider binary (holds the secp256k1 key; it NEVER leaves). | +| `ELASTOS_DDRM_WALLET_BASE` | Stable managed-key store dir (so the account survives across buys). | +| `ELASTOS_DDRM_CHAIN_ID` | The EVM chain id (e.g. `84532` for Base Sepolia). | +| `ELASTOS_DDRM_BUY_LEDGER` | The asset's channel/ledger (resolves KID→tokenId + the `buyAccess` `ledger` arg). | +| `ELASTOS_DRM_SPEND_UNIT` | meter-unit⇄pay-token mapping — the cap is a LITERAL on-chain ceiling (fail-closed: the live rail refuses to wire without it). | +| `ELASTOS_DRM_PAY_TOKEN` | The required pay-token; a listing in any other token is refused (abort-on-drift). | +| `ELASTOS_DRM_MIN_CONFIRMATIONS` | Depth floor before a buy promotes to charged (default 3). | +| `ELASTOS_DRM_RECONCILE_INTERVAL_SECS` | Arms the in-runtime confirmation scheduler (unset ⇒ manual reconcile). | +| `ELASTOS_CHAIN_READ_DEADLINE_SECS` | Per chain-conversation deadline (default 30; set above your P99 RPC roundtrip). | + +## 2. Grant → Act → Prove + +1. **Mint the managed account & fund it.** Start the gateway with the env above; the managed + account address is minted deterministically on first wallet use. Fund that address with testnet + gas + the pay-token, and confirm the ACCESS_TOKEN listing is active for it. +2. **Grant** a pay-mandate scoped to the asset with a cap that covers `price × 1` (quantity is pinned + to 1 — a buy is one ACCESS_TOKEN): use the Mandates shell app (or `mandate_cmd grant`). +3. **Act.** Have the agent dispatch a signed `runtime.pay` intent bound to that mandate (or drive the + `market-demo` quote-then-buy). The buy path: quote the on-chain price (read-only, refuses if the + cap can't cover it) → durably custody the reservation `Pending` on the ledger (now tagged + `PaymentRail::Drm`, Sprint 44) → sign in the wallet capsule → broadcast → return `Indeterminate` + with the `drm:tx=;…` rail_ref. The reservation is HELD, never charged at broadcast. +4. **Confirm.** The scheduler (or a manual `reconcile`) reads the receipt: mined + `status==0x1` + + ≥ `ELASTOS_DRM_MIN_CONFIRMATIONS` deep ⇒ promote to charged and bind the receipt's token-keyed + `CapabilityUse.rail_ref`; reverted ⇒ refund exactly once; not-yet-mined/unreadable ⇒ stay Pending. +5. **Prove.** Export the `MandateReceipt` and verify it OFF the box: + `elastos verify-receipt ` — it re-checks the signed chain and shows the bound + `rail_ref` (`drm:tx=…;price=…;tok=…`). This is the portable proof a third party trusts. + +## 3. What each failure means (the money direction, by construction — Sprint 43) + +- **Refused before broadcast** (wallet-not-linked, sold out, price/pay-token drift, sign-leg timeout, + a missing signature): `BuyError::PreBroadcast` ⇒ **refund** — the tx was provably never sent. +- **Failed at/after broadcast** (send-leg RPC error/timeout, a post-broadcast bookkeeping failure): + `BuyError::Indeterminate` ⇒ **hold** the reservation; reconciliation resolves it from the chain. + A hostile provider's error text can NOT flip this — the variant is the code path, not the string. + +## 4. The live-buy integration test (network-gated) + +The real-buy test is `crates/elastos-server/tests/live_drm_buy.rs`, compiled ONLY under the +`live-chain` cargo feature and additionally `#[ignore]`d — so it is never built, let alone run, by +the default gate (which has no funded wallet or live RPC). It drives the real `ChainDrmMarketplace` +(resolve → on-chain price gate → sign → broadcast) via `DrmMarketplaceProvider::pay`, then polls +`ChainDrmMarketplace::confirm` until the depth floor is met — asserting the buy is HELD +(`Indeterminate` with a real `drm:tx=`, never charged at broadcast) and then confirms on-chain. + +Run it deliberately, with the §1 environment plus three test-only vars +(`ELASTOS_LIVE_BUY_ASSET`, `ELASTOS_LIVE_BUY_CAP`, `ELASTOS_LIVE_BUY_PRINCIPAL`): + +```sh +cargo test -p elastos-server --features live-chain --test live_drm_buy -- --ignored --nocapture +``` + +> **This has not yet been run against a live testnet in this repo.** The first operator to run it +> should record the resulting tx hash here. **A re-run re-spends:** this standalone test bypasses the +> runtime's ledger dedup and `ChainDrmMarketplace::settle` ignores the idempotency key, so re-running +> after a broadcast issues a SECOND real buy — resolve the prior tx on-chain first. (The +> gateway-driven flow in §2 does NOT have this hazard: its `begin_attempt` custody + `flint-` +> idempotency refuse a re-charge.) + +The GATE-runnable half — that the receipt a confirmed buy produces is an admissible artifact through +the standalone `verify-receipt` CLI (AUTHENTIC with the pinned signer; INVALID if the settlement +reference is edited) — runs on every push: +`verify_receipt_cmd::{a_drm_settlement_receipt_verifies_authentic_through_the_cli, +a_tampered_drm_rail_ref_is_invalid_through_the_cli}`. Keep the live test OUT of the default gate — a +test that spends real value or needs a network must never run on every push. diff --git a/docs/NORTH_STAR_FLINT.md b/docs/NORTH_STAR_FLINT.md new file mode 100644 index 00000000..24f154d5 --- /dev/null +++ b/docs/NORTH_STAR_FLINT.md @@ -0,0 +1,215 @@ +# North Star — Flint + +*The production strategy. Audited to convergence by a cross-industry 0.01% board — +category founder, vertical-SaaS unicorn operator, AI-rights dealmaker, marketplace +economist, sovereign-systems architect, securities/IP counsel, and a contrarian VC +whose only job was to steelman the pass. Grounded in first principles and 5-Whys. +This version reflects the board's convergence and the objections that survived it.* + +--- + +## One sentence + +**Give your AI a mandate, not your keys.** + +Flint is the **accountability layer for AI agents that act** — the runtime where an +agent's authority is *physically bounded* (scoped, capped, revocable) and *every +action produces admissible, tamper-evident proof*: authorization before, signed +record after. A broker that works *for* you under authority you can watch and +revoke — not a twin that *is* you. + +## The wedge (where we enter) + +**Agent PAM — privileged-access management for AI agents in regulated enterprises.** + +Every agent company hits the same wall: the moment an agent touches money or +credentials, the CISO, auditor, or insurer says *no* — because today "give the agent +access" means handing over unscoped, irrevocable, unauditable keys. Flint replaces +those keys with a **mandate**: a signed, scoped, spend-limited, revocable grant the +runtime *cannot exceed* (in-guest limits, signed refusals), plus a tamper-evident +audit chain that proves exactly what was authorized and what happened. + +This is not new budget — it is the **existing non-human-identity / PAM line +(CyberArk-class money) relabeled "AI agent security,"** owned by the CISO and funded +this fiscal year. We are **unblocking a committed spend**, not creating demand. The +buyer already has a board-promised ROI number that is stuck behind one sentence: *"the +agent holds credentials we can't scope, revoke, or prove anything about."* + +**Why this and not the marketplace/DRM wedge:** the board killed "lead with data/ +likeness licensing." A revocable key protects *future access* to bytes; but AI +training is a **one-shot extraction** — the transaction's whole point is to let the +content enter a model, and once ingested it cannot be revoked. Selling enforcement of +a boundary the use-case requires crossing is a losing physics. So DRM is **act two** +(assets licensed *into* the agent's boundary), never the entry. + +## Bedrock (5-Whys) + +Why do enterprises pay? Because agents are blocked. → Why blocked? Security can't +scope or revoke what an agent with keys can do. → Why does that matter? An unbounded +agent is unbounded liability. → Why does Flint fix it? A mandate bounds the action +*ex-ante*; the audit chain proves it *ex-post*. → **The irreducible why: they are not +buying security — they are buying *admissible evidence* that converts unbounded +liability into a signed, bounded, provable one, which unlocks headcount-scale savings +from agent labor.** The scarce commodity in an agent economy is not compute, models, +or data (all abundant or rented) — it is **checkable accountability: provable +authorization before an act, provable record after.** That is *delegation without +abdication*, and it is symmetric: the owner needs capped authority, the counterparty +needs a verifiable mandate, the regulator needs the record. All three buy the same +primitive, and this runtime already manufactures it. + +## The interface — a Knowledge Navigator for owned action + +Apple's 1987 Knowledge Navigator is remembered for predicting the iPad and Siri. It +actually predicted the one thing Big Tech still hasn't shipped: **one intelligent +interface that collapses apps, search, files, meetings and context into intent.** +Flint ships that missing half — not the assistant that *understands*, but the +assistant you can *constitutionally empower*. + +**What the user sees:** one surface. A **conversation** on the left, a **living +canvas** on the right. No apps, no file manager, no settings pages. + +- **Intent → Mandate.** You speak intent ("renew our SaaS licenses this quarter, cap + $4,200, cancel anything unused 60 days"). Flint's first render is not an answer — it + is a **mandate card** on the canvas: scope, cap, duration, a revoke button. You sign + it with one gesture. *That is the entire permissions dialog for your digital life.* +- **Action → Receipt.** As the agent works, the canvas becomes a timeline of **receipt + tiles** — each shows its authorization above and its signed record below. Refusals + render in-line: *"declined: would exceed cap — here is the signed refusal."* +- **The audit chain IS the Finder.** Search, files, and history collapse into one + thing: your past is a browsable ledger of intents fulfilled. Any tile can be pulled, + disputed, or handed to an auditor. +- **Assets appear as keys.** A dataset, a colleague's agent-skill, a licensed voice + show up as keys the agent checks out and returns — the bytes never leaving + containment. (This is where act-two licensing lives, inside the same surface.) + +The loop *is* the UI: **intent → mandate → action → receipt.** ElastOS remains the +free, classic desktop shell underneath; Flint is the intent surface you flip to. Same +runtime under both, so switching is instant. + +## Why a company, not a feature — and the moat + +The mandate + receipt is a **two-sided protocol with Visa-shaped network effects**: +every counterparty (bank, vendor, auditor, insurer) that accepts a Flint receipt makes +every future mandate more valuable, and every delegated dollar becomes a natively +tollable event. Models commoditize; the trust rail *underneath* delegated action does +not. + +**The moat vs the obvious competitors (Okta / Entra Agent ID / MCP permissioning):** +identity systems issue and scope credentials — they answer *who*. They **cannot prove +an agent didn't exceed its authority at execution time, and cannot produce a +tamper-evident receipt.** Flint enforces at the **runtime/execution layer** (the agent +*physically cannot* exceed the mandate; refusals are signed; metering is +hardware-proven) and emits an **admissible record.** Identity says *who could*; Flint +proves *what actually happened.* The defensible seam is **enforcement + admissible +evidence**, not the credential — and the durable moat is to make *"signed mandate + +signed record"* the thing auditors and examiners ask for **by name**, i.e. a +compliance standard a platform bundle can't casually replicate. + +## The honest pass, answered (the contrarian's objections) + +A top-tier VC steelmanned the pass. The objections that survived, and the counters: + +1. **"Consent/liability is handled by contracts + insurance, not cryptography."** True + for the *data-licensing* wedge — which is exactly why we don't lead with it. For the + *agent* wedge, the buyer is not indemnifying a data claim; they are trying to + *deploy agent labor at all*, and the blocker is technical (can't scope/revoke/prove), + so the fix must be technical. +2. **"The DRM boundary is voided by the very transaction it enables."** Conceded — for + training data. Agent accountability does not require the data to cross a boundary; it + requires the *action* to be bounded and proven. Different physics. +3. **"Differentiated claims are unbuilt; built claims are undifferentiated; the + 'decentralized' quorum is one trust domain and a red team will find it."** The most + important operational truth in the deck: **lead only with what ships** (fail-closed + mandates, signed refusals, the audit chain — hardware-verified), state the + trust-domain boundary *honestly before* diligence finds it, and drop "decentralized/ + post-quantum" from the enterprise pitch entirely — sell *"bounded, provable agent + authority,"* not crypto vocabulary. +4. **"Distribution: the mandate layer lives where the agent lives; hyperscalers bundle + good-enough governance."** The real war, and named as our #1 risk. The counter is + speed to a **standard**: be in the frameworks and on the auditors' checklists within + ~24 months, because *"provably could not exceed the mandate"* is not a system-prompt + feature a bundle replicates. + +**The single flip condition (pass → conviction):** one production deal where a +counterparty's *risk owner* — an auditor, an insurer, or a bank's control function — +formally **accepts a Flint receipt as evidence** (a priced reduction in audit cost, an +insurance discount, or an examiner's sign-off), i.e. a deployment that demonstrably +could not have shipped on OAuth-scopes-plus-a-virtual-card alone. That one artifact +converts "logged" into "admissible" and the company from "runtime with a narrative" +into "the instrument that unlocks agent labor in regulated work." + +## First customer, and why now + +**First customer:** an **outsourced finance-ops / AP firm** (a mid-size accounting or +bookkeeping shop, ~50 seats) whose agents pay vendor invoices — they touch client +money daily, their auditors already demand evidence trails, and they buy today at +$500+/seat/month. They are the exact node that turns receipt-acceptance from theory +into precedent. **Beachhead-adjacent:** a regulated enterprise's agent-platform team +(bank/insurer/fintech) with ops agents (claims, KYC, reconciliation, treasury) stuck +in security review. + +**Why now (2026):** agent pilots are hitting production in regulated shops this year; +EU AI Act and model-risk scrutiny land now; every buyer has a committed ROI blocked by +the credential problem. We meet the moment; we don't manufacture it. + +## The compounding path ($10M → $100M → $1B) + +- **$10M — Agent PAM (SaaS).** 40–60 regulated enterprises at $150–250K ACV for + mandate issuance + revocation + audit-chain retention. Okta-shaped: security budget, + annual contract, compliance checkbox. +- **$100M — Metered authority (usage).** As fleets go 10 → 10,000 agents, turn on the + built metering: per-mandate / per-action pricing with in-guest limits and signed + refusals, plus compliance-reporting SaaS on the audit chain (the regulator-facing + artifact is itself a product). Twilio/Auth0 economics. +- **$1B — The clearing layer (take-rate).** Two natively tollable events: (1) bps on + agent-authorized spend — *interchange for agent commerce*; (2) per-open key-release + toll on assets licensed *into* the boundary (data, models, premium content sold to + agents with cryptographic proof the bytes never escaped). Visa-shaped: both + authority-out and assets-in clear through you. + +**Monetize first:** flat per-agent SaaS + audit retention (CISO-approvable, no +usage-pricing procurement allergy on a new category). Instrument every metering and +key-release event from day one; **do not toll until volume exists.** + +## Where the earlier vision re-enters (honestly sequenced) + +- **Act one (now):** the accountable agent — authority *out*. +- **Act two:** licensing *in* — datasets/models/voices as revocable, metered keys the + agent consumes inside the boundary. Positioned as a **royalty rail + liability + shield** (Spotify made licensed access cheaper than theft and took a cut), never as a + lock; concede the analog hole and one-shot extraction. Supply-first via one marquee + rights-holder. The default-FALSE, purpose-scoped, revocable **training-rights grant** + is the strongest primitive here — keep it. +- **Act three (after ~12+ months of real GMV):** the marketplace and the **royalty + market** — and only as *indices* underwritten on realized on-chain revenue, sold to + accredited/institutional buyers under a real securities wrapper (Reg D/Reg S, + KYC-enforced, transfer-restricted at the contract level, bundles via SPV+adviser). + Royalty *accounting* (splits, receipts, statements) ships from the first sale; the + *exchange* comes much later. Note the **issuer-is-oracle** conflict — the metered + on-chain receipt is what makes the revenue feed independently attestable. + +## What we are deliberately NOT doing + +- **Not** leading with a consumer creator marketplace (two-sided cold start, no urgent + budget, 25 years of consumer-DRM corpses). +- **Not** promising "everyone's data becomes capital" (individual data ≈ $0; value is + demand, not protection — it survives only as *pooled, consented* collective + licensing). +- **Not** promising "frontier AI at home" (frontier is rented; *your* model is owned — + sovereignty, privacy, and the marginal cost of your tokens, personalized via RAG + + a LoRA adapter + memory, hard tasks routed through a **signed declassification + gate**). +- **Not** claiming "decentralized/sovereign" until the quorum leaves one trust domain + and the peer plane is authenticated; **not** claiming tamper-*proof* — we ship + tamper-*evident*. + +## The one strategic bet + +**Ship Carrier peer authentication + a counterparty-verifiable signed mandate, and +land ONE deal where a real risk owner (auditor / insurer / bank control function) +accepts a Flint receipt as evidence for a money-touching agent.** That single +transaction proves the mandate (authority a counterparty can verify), the enforcement +(the agent physically couldn't exceed it), and the admissible record (the receipt) — +"give your AI a mandate, not your keys," as a working economy, not a slogan. Everything +else — the licensing rail, the marketplace, the royalty market, the sovereign mesh — is +an expansion of that one proven primitive. diff --git a/docs/PAYMENT_ENDPOINT_CONTRACT.md b/docs/PAYMENT_ENDPOINT_CONTRACT.md new file mode 100644 index 00000000..45121d0f --- /dev/null +++ b/docs/PAYMENT_ENDPOINT_CONTRACT.md @@ -0,0 +1,73 @@ +# The Flint Payment Endpoint Contract + +**Audience:** the engineer implementing the payment adapter a Flint runtime pays through — the +HTTPS service named by `ELASTOS_PAYMENT_ENDPOINT`. Typically a thin service in front of your real +rail: Stripe, ACH, a treasury system, or a crypto settlement layer. Flint does not care which; it +cares that you answer honestly. + +## What Flint sends + +One `POST` per payment attempt: + +``` +POST +Authorization: Bearer (when configured) +Idempotency-Key: flint- +Content-Type: application/json + +{ "payee": "", "amount": , "idempotency_key": "flint-" } +``` + +- `payee` is a 1-64 char slug (`[A-Za-z0-9._-]`), already authorized by the operator's mandate. + Your adapter owns the mapping from slug → real account/beneficiary. +- `amount` is a whole number of spend units. The unit (cents, sats, credits) is a deployment + agreement between you and the operator; Flint enforces the cap in the same unit. +- The `Idempotency-Key` is unique per signed payment intent and NEVER reused for a different + payment. **You MUST deduplicate on it**: if you have seen the key before, return your original + result without charging again. This is what makes crash-retry and reconciliation safe. + +## What your status codes MEAN to Flint (read this twice) + +Flint runs a fail-closed spend cap. Your status code decides whether the runtime **refunds** the +reserved budget or **holds** it — answer wrongly and you can make real spend exceed the operator's +cap. + +| You answer | Flint concludes | Flint does | +|---|---|---| +| **2xx** (any, incl. `202`) | The charge **HAPPENED**. Body (≤64 KiB read, first 256 printable chars kept) = your transaction reference. | Mints a signed `performed` receipt; records your reference in the payment ledger (best-effort — a full or failed ledger drops it to the runtime log). **Never return 2xx for an order you only queued but might reject.** | +| **4xx** (any, incl. `408`, `429`) | The charge **PROVABLY DID NOT happen**. | **Refunds** the cap reservation. **Never return 4xx for an order you may have (or did) process** — that refund plus your real charge is a cap breach. If you must shed load, use `503`. | +| **5xx** | **INDETERMINATE** — you received the order; the outcome is unknown. | **Holds** the reservation and files a pending entry the operator later reconciles against you by idempotency key. | +| **3xx** | Indeterminate. Flint never follows redirects for money orders. | Holds the reservation. Don't redirect. | +| (timeout / connection drop after send) | Indeterminate. | Holds the reservation. | +| (connection refused / TLS failure before send) | Provably not sent. | Refunds. | +| (timeout during the connect phase, or a `1xx`) | Classified **indeterminate** (fail-closed: the runtime cannot distinguish a connect-phase timeout from a post-send one). | Holds the reservation. | + +**The one rule that matters:** *only* say "not charged" (4xx) when you can prove it; *only* say +"charged" (2xx) when it is true; everything else is 5xx. Flint keeps every unclear reservation and +gives the operator a reconciliation surface — ambiguity is safe, dishonesty is not. + +## Reconciliation + +For every indeterminate outcome the operator will query you (out-of-band today: your dashboard or +API) with the `Idempotency-Key`, and then tell Flint the verdict via +`POST /api/payments/reconcile { idempotency_key, charged }`. Your adapter should therefore be able +to answer, for any key it has ever seen: *did this order charge, and what was the reference?* +Retaining keyed results for at least the operator's reconciliation window (recommend ≥90 days) is +part of the contract. + +## Transport & trust + +- **HTTPS is required.** Flint refuses to wire a plaintext endpoint (loopback excepted, for a + same-box sidecar adapter). +- Authenticate the bearer token; a runtime configured without one warns loudly at boot and expects + you to authenticate callers another way (mTLS, network policy). +- **You are fully trusted about money movement.** A 2xx from you mints a signed receipt Flint's + runtime cannot independently verify — a `performed` payment receipt is a *rail-trust* + attestation. Protect this endpoint like the payment credentials it fronts. + +## Quick self-test + +Your adapter is contract-correct when: (1) replaying the same `Idempotency-Key` never double +charges; (2) no code path returns 4xx after money moved (or might move); (3) no code path returns +2xx before the charge is definitely committed; (4) you can answer charged/not-charged for any past +key on demand. diff --git a/docs/README.md b/docs/README.md index 7e326e50..71068f32 100644 --- a/docs/README.md +++ b/docs/README.md @@ -37,6 +37,11 @@ Planning and truth surfaces outside `docs/`: - [ARCHIVE_POLICY.md](ARCHIVE_POLICY.md) — Archive dependency, release, and generic-family enablement policy - [PC2_CONVERGENCE.md](PC2_CONVERGENCE.md) — current translation of useful PC2 patterns into Runtime provider/capsule boundaries - [CHAIN_PROVIDER.md](CHAIN_PROVIDER.md) — typed chain-provider boundary and current blockchain-quadrant slice +- [FLINT_MANDATE_ENGINE.md](FLINT_MANDATE_ENGINE.md) — Flint, the mandate engine: scoped/revocable agent authority, the spend-capped payment spine, portable signed receipts (entry point for the mandate/payment subsystem) +- [DRM_MARKETPLACE_RAIL.md](DRM_MARKETPLACE_RAIL.md) — the DRM marketplace payment rail: wiring, operator runbook, honest bounds +- [PAYMENT_ENDPOINT_CONTRACT.md](PAYMENT_ENDPOINT_CONTRACT.md) — the stated contract an HTTPS payment endpoint must honor +- [KNOWN_GAPS.md](KNOWN_GAPS.md) — the build-visible gap registry (runtime-wide), the honest ledger every closed/open gap lands in +- [CODE_QUALITY_LEDGER.md](CODE_QUALITY_LEDGER.md) — deferred structural cleanups from the standing quality audit - [WALLET_PROVIDER.md](WALLET_PROVIDER.md) — wallet proof, account-link, typed-signing, and transaction authority boundary - [BROWSER_CAPSULE.md](BROWSER_CAPSULE.md) — Browser/Net/Exit/Engine ABI, product rule, and current proof boundary - [BROWSER_PROVIDER_BAKEOFF.md](BROWSER_PROVIDER_BAKEOFF.md) — hosted/native browser-provider comparison and acceptance gates diff --git a/docs/SPEC-mandate-v1.md b/docs/SPEC-mandate-v1.md new file mode 100644 index 00000000..cc668fc7 --- /dev/null +++ b/docs/SPEC-mandate-v1.md @@ -0,0 +1,230 @@ +# Mandate & Receipt Wire Format — v1 (Sprint 49) + +The portable formats behind Flint's "Grant → Act → Prove" loop, specified to the byte so an +independent party can (a) verify a `MandateReceipt` with no Flint code — completely for +`capability`-scope receipts and for `contiguous` receipts composed of the §5 events (other event +variants' serialized shapes live in the code, not yet in this spec), PROVIDED the implementation +uses a byte-compatible JSON encoder (§2's canonicalization rules; a mismatched encoder produces +false NEGATIVES, never forgeries) — and (b) construct a signed intent a Flint runtime will +accept. Everything here is FROZEN: verification re-serializes and +re-hashes these shapes, so any change is a new versioned schema, never an edit. A conformance +ratchet (`primitives::audit::tests::the_wire_format_matches_spec_mandate_v1`) pins this document +to the code. + +Primitives: SHA-256; ed25519 (RFC 8032) verified STRICTLY (canonical S, small-order keys +rejected — two conforming verifiers must never disagree on a malleated signature); base64 +(standard alphabet, padded, canonical trailing bits) for signatures; lowercase hex for hashes and +keys (verifiers SHOULD reject non-lowercase — the §4 binding signs the literal ASCII bytes); +JSON with the field names and order given here (serde-emitted; order is declaration order). +Domain separation between the three signature contexts (§2 record, §4 binding, §7 intent) rests +on the domain strings INSIDE each preimage — not on message length (two of the three signed +values are 32 bytes). + +## 1. Trust model (read first) + +- **Self-asserted signer.** A receipt verifies against the ed25519 key *it carries* + (`signer_public_key_hex`). Anyone can mint a key and fabricate a receipt that verifies against + itself. A consumer MUST pin the expected issuer key out-of-band (the `--signer` argument / + `expected_signer_hex`); an unpinned verification is a structural check, **not a trust decision** + (exit code 3, never 0). +- **Tamper-evident, not tamper-proof.** The format detects edits, interior drops, additions, and + reorders by a HOLDER in transit (including of the settlement reference) — with ONE exception: + a `contiguous` receipt WITHOUT a `set_binding` does not detect records truncated off the END + together with the binding field (linkage fixes the interior, not the end; demand a bound + receipt if end-truncation matters). It does not bind the key-holding ISSUER: a compromised + runtime can sign a fabricated or selective set. +- **As-of-export, not as-of-now.** A receipt (and its §4 binding) fixes the set *at export + time*. A holder possessing an earlier honestly-signed export (e.g. pre-revoke) can present it + and every check passes. A consumer needing currency MUST demand a fresh export; the format + carries no freshness anchor. +- **Completeness bounds.** A `contiguous` receipt proves an unbroken run but records truncated off + the END need an external head anchor to detect. A `capability` receipt proves no *holder* altered + the set (§4) but cannot prove the issuer omitted nothing at export. + +## 2. The chained record + +One audit record as it appears in a receipt (and on disk, one JSON object per line): + +```json +{ + "seq": 1, // u64, monotonic, first record = 1 + "prev_hash": "<64 hex>", // prior record_hash; genesis = 64 zeros + "event": { … }, // the audited event (§5) + "record_hash": "<64 hex>", // see below + "alg": "ed25519", // or "none" (unsigned logs; receipts REQUIRE ed25519) + "sig": "" // ed25519 over the 32 raw record_hash bytes; "" iff alg=none +} +``` + +**Record hash preimage** (concatenation, no separators): + +``` +record_hash = SHA-256( "elastos.runtime/audit-chain/v1" // domain, ASCII, no NUL + ‖ seq as 8-byte big-endian + ‖ prev_hash as 32 raw bytes + ‖ event_json ) +``` + +`event_json` is the event's canonical serde-JSON serialization. Verifiers MUST re-serialize the +*deserialized* event and hash those bytes (never the bytes as received) — this is the one +canonicalization recipe, shared by the on-disk chain walker and the receipt verifier. + +**Record signature:** ed25519 over the 32 raw bytes of `record_hash` (not the hex string). + +## 3. The mandate receipt document + +```json +{ + "schema": "elastos.mandate_receipt/v1", // verifier fail-closes on any other value + "signer_public_key_hex": "<64 hex>", // the issuing runtime's ed25519 key (§1 caveat) + "scope": { "kind": "contiguous" } // or: + { "kind": "capability", "token_id": "" }, + "records": [ ChainedRecord, … ], // ascending seq; records[0] = the mandate grant + "set_binding": "" // §4; REQUIRED for capability scope, else optional +} +``` + +An absent `scope` key means `contiguous` (legacy). By convention `records[0]` is the +`capability_grant` (the mandate) and the rest are the acts taken under it — but verifiers MUST +NOT require the grant at index 0 (the capability rule is "exactly one grant", position-free). + +## 4. The set binding + +The issuer's signature fixing the exact ordered record set — what stops a holder trimming a use or +revoke in transit from a `capability` receipt (whose membership is otherwise a keyless filter). +Ed25519 over: + +``` +binding_message = "elastos.runtime/mandate-receipt-set/v1" // domain, ASCII + ‖ scope_tag // 1 byte: 0=contiguous, 1=capability + ‖ [ len(token_id) as 8-byte BE ‖ token_id bytes ] // capability scope only + ‖ record_count as 8-byte big-endian + ‖ concat( record_hash as the 64 ASCII hex bytes, in order ) +``` + +Note the record hashes enter as their 64-char ASCII hex (fixed width — position + count make the +encoding unambiguous), not as raw bytes. + +## 5. Mandate-relevant events + +Events are a serde `AuditEvent` enum, INTERNALLY tagged: the variant name rides a `"type"` field, +FIRST, followed by the variant's fields in declaration order (snake_case). Because `event_json` +is hashed (§2), the byte encoding is normative: COMPACT JSON (no whitespace), keys in exactly the +order shown, serde_json string escaping (control chars escaped; `/` NOT escaped; non-ASCII as raw +UTF-8, never `\uXXXX`). The three events the mandate loop uses, as +byte-exact templates (`timestamp` is `{"unix_secs":u64,"monotonic_seq":u64}` — wall clock plus a +monotonic counter that survives clock steps): + +```json +{"type":"capability_grant","timestamp":{…},"token_id":"…","capsule_id":"…","resource":"…","action":"…","expiry":null} +{"type":"capability_use","timestamp":{…},"token_id":"…","capsule_id":"…","resource":"…","action":"…","success":true} +{"type":"capability_revoke","timestamp":{…},"token_id":"…","reason":"…"} +``` + +- **`capability_grant`** — the mandate itself. `expiry` is a nullable timestamp (literal `null` + when unset); optional `responsible_entity` (the accountable legal-entity DID) is APPENDED after + `expiry` when set and ABSENT — not null — when unset (a frozen rule so pre-S32 chains + re-verify). +- **`capability_use`** — one act. Optional `rail_ref` is APPENDED after `success` when set, + ABSENT for non-rail acts: the external settlement reference for money acts (currently + `drm:tx=;op=…;tid=…;price=…;tok=…` or `erc20:tx=;to=…;amount=…;tok=…` — see + SPEC-market-provider-v1 §4; the key lists are informative — a receipt verifier treats + `rail_ref` as an opaque string). +- **`capability_revoke`** — the kill switch: exactly `type`, `timestamp`, `token_id`, `reason` + (there is NO `capsule_id` on a revoke). + +Exact field lists are pinned by the conformance ratchet; any addition must be +`#[serde(default, skip_serializing_if = …)]`-append-only so old chains re-serialize byte-identically. + +## 6. Verification algorithm + +Given a receipt and an optional pinned signer key, compute the verdict: + +1. `schema == "elastos.mandate_receipt/v1"` and `records` non-empty, else INVALID (hard error). +2. Decode `signer_public_key_hex` → 32-byte ed25519 key, else INVALID. +3. For each record, in order: + a. **Linkage** (records after the first): `prev_hash == prior.record_hash` and + `seq == prior.seq + 1`, else `chain_linkage_ok = false`. + b. **Hash**: re-serialize `event`, recompute §2's preimage, compare to `record_hash`, else + `hashes_ok = false`. + c. **Signature**: `alg` MUST be `"ed25519"`; verify `sig` over the *recomputed* hash bytes — + NEVER over the claimed `record_hash` (verifying the claimed bytes would let a tampered + event ride a self-consistent hash+sig pair) — else `signatures_ok = false`. +4. **Scope rule** (`scope_ok`): + - `contiguous`: `chain_linkage_ok` (nothing interior dropped). + - `capability`: every record's event carries the scope's `token_id` AND exactly one record is a + `capability_grant` AND `seq` is strictly ascending. +5. **Set binding** (`set_binding_ok`): a PRESENT `set_binding` MUST verify over §4's message for + BOTH scopes ("optional" governs only whether ABSENCE is permitted — a present-but-stale + binding is INVALID, never skipped). Absence: REQUIRED for `capability` scope (absent/null ⇒ + false); permitted for `contiguous` (absent AND null both accepted — Flint emits `null` for + unsigned contiguous exports). + Edge behaviors an implementation must reproduce: an undecodable `prev_hash` fails BOTH + `hashes_ok` and `signatures_ok` for that record and processing continues; a record whose event + cannot be re-serialized is a hard INVALID verdict (early error); `record_hash`/`prev_hash` hex + case is tolerated when decoding in step 3, but §4 signs the LITERAL ASCII bytes of + `record_hash` as stored — a case change breaks the set binding. +6. `structurally_valid = hashes_ok ∧ signatures_ok ∧ scope_ok ∧ set_binding_ok` — note linkage + participates only THROUGH `scope_ok` (it IS the contiguous scope rule; a capability receipt is + non-contiguous by design and reports `chain_linkage_ok` informationally). +7. `authenticated = structurally_valid ∧ (a pinned key was provided ∧ it matches the receipt's + key — compared trimmed, ASCII case-insensitively)`. +8. Informational: `starts_at_genesis` (records[0] has `seq == 1` and an all-zero `prev_hash`) — + the front-truncation signal for contiguous receipts; N/A to capability scope. + +**Exit codes** (the `elastos verify-receipt` contract, scriptable): `0` AUTHENTIC (pinned + +matched + structurally valid) · `1` INVALID (any structural check failed — tampered/forged) · +`3` VALID-BUT-UNAUTHENTICATED (structurally sound, no/mismatched pin — NOT a trust decision) · +`4` COULD-NOT-EVALUATE (unreadable file / malformed JSON / bad pin argument — deliberately distinct +from 1 so "couldn't read it" is never mistaken for "forged"). + +## 7. The signed intent (agent → runtime) + +What an agent signs to act under a mandate. The `schema` field's exact value is +`"elastos.intent.declaration.v1"` (dots, not slashes — it enters the signature preimage): + +```json +{ + "schema": "elastos.intent.declaration.v1", "intent_id": "…", "capsule": "vm-", "method_id": "runtime.pay", + "input_hash": "…", "resource": "…", "action": "…", "standing_grant_id": "", + "declared_at": {"unix_secs": u64, "monotonic_seq": u64}, "signer": "<64 hex>", "signature": "" +} +``` + +**Signature preimage** — ed25519 over `SHA-256` of: + +``` + "elastos.intent.declaration.v1\0" // domain, WITH trailing NUL +‖ for each of [schema, intent_id, capsule, method_id, input_hash, + resource, action, standing_grant_id, signer]: + len(field) as 8-byte LITTLE-endian ‖ field bytes +‖ len(declared_at_json) as 8-byte little-endian ‖ declared_at_json +``` + +where `declared_at_json` is the timestamp's serde-JSON encoding +(`{"unix_secs":…,"monotonic_seq":…}` — its field order is therefore frozen: +`the_signature_preimage_timestamp_encoding_is_frozen` pins that segment, and the known-answer +ratchet `the_intent_preimage_digest_is_frozen` pins the WHOLE preimage — domain, field order, and +the little-endian prefixes — as one fixed digest). Note the +length prefixes here are LITTLE-endian, unlike §2/§4 — an implementation must not assume one +endianness across domains. + +The runtime enforces, before executing: signature validity (strict); `signer` matching the +mandate's bound agent key WHEN the mandate bound one (an unbound legacy mandate is +capsule-string-scoped only); the mandate's scope/expiry/revocation; replay (the `intent_id` +inside a bounded time window); and per-mandate rate + spend budgets. Separately, the +signature-derived key `flint-` is the PAYMENT idempotency key +(SPEC-market-provider-v1 §2) — distinct from the replay key. + +## 8. Versioning + +- Serialized shapes in §2–§5 and §7 are FROZEN — verification re-serializes them. New fields must + be optional AND absent-when-unset (`skip_serializing_if`) so historical bytes are reproduced. +- Any breaking change mints a new schema tag (`…/v2`); verifiers fail closed on unknown tags. +- The three domain strings (§2, §4, §7) are part of the format; they never change within v1. + +## Version history + +- **v1 (Sprint 49):** initial publication, extracted from the shipped implementation + (`elastos-runtime::primitives::audit`, `capability::intent`) and pinned by the conformance + ratchet. diff --git a/docs/SPEC-market-provider-v1.md b/docs/SPEC-market-provider-v1.md new file mode 100644 index 00000000..38f1785f --- /dev/null +++ b/docs/SPEC-market-provider-v1.md @@ -0,0 +1,125 @@ +# Market Provider Contract — v1 (Sprint 48) + +The contract a payment/market vertical implements to settle `runtime.pay` acts under a Flint +mandate. Two shipped verticals implement it — the DRM marketplace (`DrmMarketplaceProvider`) and +the ERC-20 checkout (`Erc20CheckoutProvider`) — plus the generic HTTP rail +(`HttpPaymentProvider`). A third party should be able to implement a provider from this document +alone; where the runtime enforces an obligation mechanically (a type, a required trait method, a +gate ratchet), that enforcement is named. + +## 1. The seam + +```rust +pub trait PaymentProvider: Send + Sync { + fn pay(&self, payee: &str, amount: u64, idempotency_key: &str) -> Result; + fn rail(&self) -> PaymentRail; // REQUIRED — no default (compiler-enforced, S44/S46) +} +``` + +The runtime — never the provider — owns: the mandate gate (signed intent, scope, rate budget, +liability DID), the spend meter (cap reservation before `pay`, refund on `NotCharged`), the +payment ledger (record-BEFORE-broadcast custody, resolve-exactly-once), the signed receipt chain, +and reconciliation. A provider moves value on its rail and reports honestly. That split is the +contract's core: **a provider cannot be trusted with a money decision, only with a money report.** + +## 2. The two-generals report (`pay`) + +- `Ok(rail_ref)` — the charge PROVABLY completed on the rail. Chain-settled rails NEVER return + this at broadcast (see §4). +- `Err(NotCharged(why))` — the charge PROVABLY did not happen. The runtime refunds the + reservation. Return this ONLY for failures you can prove occurred strictly before value moved. +- `Err(Indeterminate(why))` — anything you cannot prove either way. The runtime HOLDS the + reservation for reconciliation. **When unsure, always this — never guess NotCharged.** + +CLASSIFY BY CONSTRUCTION, NOT BY MESSAGE (the S43 rule): the variant must be decided by which +code path produced the failure (its position relative to the value-moving operation), never by +inspecting error text. In the shipped verticals every pre-broadcast leg is `.map_err(NotCharged)` +at its call site and every broadcast-or-after leg is `.map_err(Indeterminate)` — no +provider-controlled byte can flip the money direction. + +`idempotency_key` is unique per signed intent (signature-derived). Rails with a dedupe facility +MUST use it so a retry/reconciliation can never double-move value. + +## 3. The rail discriminator (`rail`) + +Every provider declares its `PaymentRail` variant; the runtime stamps it onto the ledger record +at `begin_attempt`. Rail-specific reconcilers select records by this STRUCTURED tag — never by +parsing the (rail-controlled) `rail_note`. `rail()` has no default implementation, so the +compiler forces every new provider to make this declaration (S46). Consequences: + +- A hostile endpoint on one rail cannot craft a note that gets its pending polled by another + rail's reconciler (gate-ratcheted for both `drm:tx=` and `erc20:tx=` forgeries on Http-tagged + records). +- Adding a `PaymentRail` variant is a forward-incompatible ledger change (an older runtime + refuses a newer snapshot — deliberate fail-closed serde posture); ship it as a coordinated + upgrade. + +## 4. Chain-settled rails: broadcast ≠ charged + +A rail that settles on a chain (DRM, ERC-20) MUST NOT report `Ok` at broadcast. The contract: + +1. `pay` broadcasts, then returns `Err(Indeterminate(rail_ref))` where `rail_ref` is + `:tx=;=;…` — compact, delimiter-stripped per component (`;`/`=` removed + from each chain-supplied value so a hostile field cannot forge the parsed binding). +2. The runtime holds the reservation as a `Pending` ledger record carrying that note + the rail + tag. +3. The provider also implements the confirmation reader (`DrmConfirmer::confirm`, shared + `confirm_chain_tx` spine): tx mined + success status + ≥ `ELASTOS_DRM_MIN_CONFIRMATIONS` + deep ⇒ `Confirmed`; mined-but-reverted ⇒ `Reverted`; anything else — including any read + error — ⇒ `Unconfirmed` (hold; NEVER auto-charge a tx you could not verify). +4. The in-runtime scheduler (or a manual reconcile) promotes `Confirmed` pendings to charged + exactly once (binding the receipt's `rail_ref`), refunds `Reverted` exactly once, and leaves + `Unconfirmed` pending. Depth gates BOTH verdicts (a shallow revert is held, not refunded — a + reorg could re-include it). + +## 5. The quote gate: the cap is a literal ceiling + +The mandate cap is denominated in meter units; the rail settles in its own units. The operator +DECLARES the mapping at wiring time (`ELASTOS_DRM_SPEND_UNIT` / `ELASTOS_ERC20_SPEND_UNIT`: +rail base-units per meter unit) and the rail REFUSES TO WIRE without it — never a silent 1:1. +A rail with variable prices (DRM listings) must quote read-only BEFORE broadcast and refuse a +settlement above the gated amount, arming abort-on-drift on both price and pay-token. A rail +with caller-specified amounts (ERC-20) computes `amount × unit` with checked arithmetic +(overflow ⇒ `NotCharged`). + +## 6. Wiring discipline (`build_pay_rail`) + +- Durable meter + ledger REQUIRED — real money on non-durable stores refuses to wire. +- Mock/synthetic settlement requires the explicit `ELASTOS_ALLOW_MOCK_PAYMENTS` opt-in (S29) and + is a `dev-modes` build capability in the shipped verticals. +- Misconfiguration refuses to wire (fail-closed) or warns loudly at boot; it never degrades to a + weaker rail silently — including the rail selector itself: an unrecognized + `ELASTOS_PAYMENT_RAIL` refuses to wire. Exactly ONE rail is wired per runtime; per-payee rail + routing is future work. +- Chain-settled rails share ONE chain configuration (P5), currently under the DDRM-era names: + `ELASTOS_CHAIN_BASE_RPC` (required for any live leg), `ELASTOS_DDRM_CHAIN_ID`, + `ELASTOS_DRM_MIN_CONFIRMATIONS` (depth floor), `ELASTOS_DRM_RECONCILE_INTERVAL_SECS`/`_BATCH` + (the scheduler). A rail-neutral rename of these env names is tracked follow-up work. + +## 7. Receipts + +On confirmed settlement the runtime binds the `rail_ref` onto the mandate's signed receipt chain +(a token-keyed `CapabilityUse`). The exported `MandateReceipt` is verifiable off-box +(`elastos verify-receipt`): AUTHENTIC with the pinned issuer key, INVALID if any signed field — +including the settlement reference — is edited. A provider's only receipt obligation is the +honest `rail_ref`; everything cryptographic is the runtime's. + +## 8. Conformance checklist + +A new vertical ships when it can answer YES to each, with a gate test per row: + +| # | Obligation | Enforced by | +|---|---|---| +| 1 | `rail()` declared | compiler (no default) | +| 2 | Pre-value failures are `NotCharged` by construction | call-site `map_err` + ratchets | +| 3 | Value-moving-op-and-after failures are `Indeterminate` | call-site `map_err` + ratchets | +| 4 | Chain rails: never `Ok` at broadcast; parseable `:tx=` ref | provider broadcast ratchet + the shared-spine e2e (DRM) | +| 5 | Confirmation reader is fail-safe (unreadable ⇒ hold) | shared `confirm_chain_tx` | +| 6 | Unit mapping declared or refuse-to-wire | wiring test | +| 7 | Hostile cross-rail note is never polled | reconciler ratchet | +| 8 | Idempotency key honored on rails with dedupe | rail-specific | + +## Version history + +- **v1 (Sprint 48):** initial contract, extracted from the DRM wedge (S34–S46) and proven + non-DRM-shaped by the ERC-20 checkout vertical. diff --git a/docs/STATE_AND_PLAN_2026-07-03.md b/docs/STATE_AND_PLAN_2026-07-03.md new file mode 100644 index 00000000..731fa99b --- /dev/null +++ b/docs/STATE_AND_PLAN_2026-07-03.md @@ -0,0 +1,125 @@ +# State of the System + Master Plan (2026-07-03) + +An eight-seat 0.01% assessment — professionals, an innovator, a visionary, an +advisor, and the four stakeholder voices — reconciled into one grade, one +architecture verdict, one UX verdict, the vision, and a single ordered plan. + +## Grade today — **6.5 / 10** ("world-class core, unfinished edges, unproven market") + +| Dimension | Grade | Verdict | +|---|---|---| +| Capability Security | **8** | Genuinely fail-closed enforcement spine | +| Cryptography & DRM | **8** | Post-quantum hybrid seal + threshold quorum, sound | +| Architecture | **7** | Clean primitives; the *trusted core is inverted* | +| Code Quality | **7** | Excellent ratchet culture; two god-files, one now-typed money path | +| Product & Monetization | **6** | Real moat, but it lives in the pre-release runtime; no traction | +| Performance | **5→** | The fsync ceiling is now **measured** (~789 durable emits/s); group-commit is the lever | +| User Experience | **5** | One beautiful room; three design systems; the money path shouts "Web3" | +| Vision / GTM | *strong* | A real category to create, entered on already-built primitives | + +**The shape:** an **8 on the hard core** (security, crypto) and a **5 on the +edges** (UX, and the two *unbuilt ends* — the buy-UI finish and Tier-3 execute). +The expensive, risky middle is done; the cheap, visible ends are not. That is an +unusually good position — you buy the grade up with edge work, not core rewrites. + +## Architecture verdict — right primitives, not-yet-optimal ordering + +**Is it the best/most-optimised/right way?** The *primitives* are — the capability +token (consent = trade = audit in one fail-closed object), the provider/carrier +seam, the signed hash-chained audit, the threshold DRM. These are best-in-class. + +**The structure is not yet optimally ordered.** The #1 debt: the **trusted core is +inverted** — `elastos-server` is ~170k LOC holding app/service logic (`content.rs` +13k, `library.rs` 7.6k) *inside* the trusted boundary, while the real TCB +(`elastos-runtime`) is ~24k. This directly weakens the "small enough to trust" +argument the whole security thesis rests on. Second: the **reach/"halo" +enforcement model is built but wired nowhere** — so "enforce, not log" is currently +*self-declared*, not core-computed. Third: god-files and a hardcoded +`RESERVED_SUB_NAMES` couple the provider taxonomy to the core. + +**The right ordering** (this is the key call): do **not** restructure now. Ship the +wedge first to earn the right to exist; pay down the trusted-core inversion +(ADR-0001) as the deliberate "make-it-best" investment *after* revenue — **except** +wire the halo + unstub the act path sooner, because those make the security *claim +true*, which is load-bearing for the pitch and the enterprise sale. + +## UX verdict — a powerful, honest prototype with one finished room + +**How it feels:** for ~30 seconds the marketplace storefront convinces you a normal +person could use this — turquoise-and-gold glass, real skeleton loaders, +focus-trapped modals, keyboard-operable cards, and radical honesty (a `live/demo` +pill, no fake progress %). Then the buy sheet renders a raw `unsigned_tx` JSON +blob and the asset page announces KID / ERC1155 / tokenId / tx hashes, and you +remember engineers built it and want you to see the plumbing. The "never say Web3" +ambition and the product are at war. + +- **Positives:** 0.01%-tier *real* accessibility in the storefront; clean + information architecture; honesty-as-UX; passkey (not seed-phrase) auth; genuine + motion craft. +- **Drawbacks:** three design systems across storefront/creator/home; the money + path leaks Web3 at every step; `curl | bash` + CLI install disqualifies the + target user; the creator flow reads like an internal tool; the open/playback + payoff moment is the least-designed screen; the signed-fact consent UI (the + conceptual heart) is spec-only. +- **UX wedges:** hide the plumbing behind a "details for nerds" disclosure *(low)*; + unify to one design system + gate drift *(med)*; real installer → passkey *(high)*; + managed-wallet + fiat on-ramp as the default buy *(high)*; design the + open/playback moment *(med)*. + +## The vision — **Sealed-Rights Commerce** + +A licensing rail where the unit of trade is a **revocable, enforced key bound to an +on-chain right**, not a copyable file. The NFT era sold receipts without locks; +this binds the token to the lock. + +- **The wedge:** premium creators and talent being AI-cloned — voice actors, + likeness rights-holders, high-end photographers/3D artists — who sell *access to* + a likeness/voice opened inside a containment boundary (buyer sees frames, never + the file/key/weights), with **training rights a separate grant defaulting to + FALSE**, at **2% vs platforms' 30–55%**. Runs on already-built, smoke-tested + primitives (the open→rights→key→decrypt loop is ~99% end-to-end). +- **Why now:** AI cloning made "sell it but keep control" survival, not + convenience; 2025–26 law (NO FAKES, EU AI Act Art. 12/14) turned consent + + provenance from nice-to-have into a budgeted mandate — logs no longer suffice, + enforcement is required. +- **3-year:** the neutral clearing-and-enforcement rail for AI-era IP; the sealed + catalog becomes the consented-provenance registry AI buyers must clear against; + the per-open key-release becomes both the toll and the liability artifact; Tier-3 + makes it the one place you can sell a runnable model whose weights never leave. + +## The single ordered master plan (by leverage) + +**NOW — done this session:** MKT-1 money-path fix (red-teamed) · `MintError` +typing · first benchmark (perf estimate → measured) · the audit + one-pager. + +**Q1 — earn the right to exist (the one bet):** +1. **Finish the draft buy-UI gate → close ONE named-creator, receipt-backed sale.** + The sole remaining gate is UI wiring, not new crypto. This is the first metric. +2. **Hide the plumbing** (UX wedge #1, low effort) — a normal buyer sees price, + "you'll own this," Confirm — not a serialized transaction. +3. **Managed-wallet "Buy with balance" default + fiat on-ramp** — or the money path + stays expert-only. + +**Q2 — reframe into the category (the centerpiece):** +4. **Ship ONE Tier-3 "runnable model, weights never leave the capsule" demo** — the + move that converts "another 2%-vs-45% marketplace" into a category only the + capsule model can serve. +5. **Wire the reach/egress model + unstub the user-approval act path** — makes + "enforce, not log" *true*; the technical-credibility spine for the pitch. +6. **Unify the design system** across creator + viewers; gate drift in CI. +7. **Pin + KAT-test the PQ crates** (`ml-dsa`/`ml-kem`) against FIPS 203/204 — the + real crypto-critical dependency. + +**Q3+ — scale + make "the best" true:** +8. **Audit group-commit** (now that ~789/s is measured) — lift the durable ceiling. +9. **Diversify dKMS nodes out of one trust domain** + recover-proof↔reseal-AAD + binding + external audit-chain anchoring — make "decentralized" honest. +10. **Pay down the trusted-core inversion** (ADR-0001: extract god-files, shrink the + TCB) — restore "small enough to trust." +11. **Carrier peer authentication** (G-CARRIER-PEER). + +## The one strategic bet + +Close **one on-chain, receipt-backed likeness/voice sale on the already-built loop +this quarter**, and spend that credibility to build the **Tier-3 demo**. Every seat +— product, vision, architecture, security — converges on this exact sequence. diff --git a/elastos/Cargo.lock b/elastos/Cargo.lock index 422a3a1d..8ef71217 100644 --- a/elastos/Cargo.lock +++ b/elastos/Cargo.lock @@ -1746,6 +1746,7 @@ dependencies = [ "elastos-storage", "flate2", "hex", + "libc", "rand 0.8.6", "serde", "serde_json", diff --git a/elastos/crates/elastos-common/src/timestamp.rs b/elastos/crates/elastos-common/src/timestamp.rs index 68e8a272..f8aff3d4 100644 --- a/elastos/crates/elastos-common/src/timestamp.rs +++ b/elastos/crates/elastos-common/src/timestamp.rs @@ -50,11 +50,14 @@ impl SecureTimestamp { /// Create a timestamp in the future (for expiry) pub fn after_secs(secs: u64) -> Self { + // Saturating: a caller-supplied ttl near u64::MAX must not overflow (a debug-build panic / + // release wrap-to-the-past). Saturating to u64::MAX yields the far-future "effectively + // never" expiry the caller asked for — red-team F5, Sprint 15. let unix_secs = SystemTime::now() .duration_since(UNIX_EPOCH) .map(|d| d.as_secs()) .unwrap_or(0) - + secs; + .saturating_add(secs); let monotonic_seq = MONOTONIC_COUNTER.fetch_add(1, Ordering::SeqCst); Self { unix_secs, diff --git a/elastos/crates/elastos-compute/src/providers/wasm.rs b/elastos/crates/elastos-compute/src/providers/wasm.rs index 220a6ebf..6f95acbd 100644 --- a/elastos/crates/elastos-compute/src/providers/wasm.rs +++ b/elastos/crates/elastos-compute/src/providers/wasm.rs @@ -613,6 +613,9 @@ impl WasmProvider { } /// Execute a WASM module with WASI preview1. + /// (8 args: the WASI plumbing genuinely needs each — an args struct here would be pure + /// ceremony. Allowed explicitly so the workspace `-D warnings` gate is truthful.) + #[allow(clippy::too_many_arguments)] fn execute_wasm( engine: &Engine, module: &Module, diff --git a/elastos/crates/elastos-runtime/Cargo.toml b/elastos/crates/elastos-runtime/Cargo.toml index 69c0e4ae..3e300d84 100644 --- a/elastos/crates/elastos-runtime/Cargo.toml +++ b/elastos/crates/elastos-runtime/Cargo.toml @@ -10,6 +10,7 @@ name = "elastos_runtime" path = "src/lib.rs" [dependencies] +libc = "0.2" elastos-common = { path = "../elastos-common" } elastos-namespace = { path = "../elastos-namespace" } elastos-storage = { path = "../elastos-storage" } @@ -47,3 +48,8 @@ tar = "0.4" [dev-dependencies] tokio = { version = "1.0", features = ["full", "test-util"] } tempfile = "3.10" + +# First throughput benchmark (audit emit ceiling). Hermetic std-timing harness, no criterion. +[[bench]] +name = "audit_emit" +harness = false diff --git a/elastos/crates/elastos-runtime/benches/audit_emit.rs b/elastos/crates/elastos-runtime/benches/audit_emit.rs new file mode 100644 index 00000000..b3187115 --- /dev/null +++ b/elastos/crates/elastos-runtime/benches/audit_emit.rs @@ -0,0 +1,146 @@ +//! First benchmark of the audit `emit` hot path — the throughput ceiling the whole runtime's +//! SPEED grade rests on. `KNOWN_GAPS` flags the audit fsync-per-record (under a global mutex) as +//! the real scalability wall AND explicitly notes it was never measured ("no flamegraph run yet; +//! magnitudes are I/O-class estimates"). This converts that estimate into a number, and — per the +//! measure-first discipline — tells us whether the group-commit rewrite is even worth its risk. +//! +//! Hermetic: std timing only, no `criterion`, no network. Run: +//! cargo bench -p elastos-runtime --bench audit_emit +//! +//! Two regimes, ops/sec + µs/op each: +//! 1. memory-only (`AuditLog::new`) — no writer, no fsync: the CPU + ed25519-sign + +//! hash-chain cost of an emit, nothing else. +//! 2. file-backed (`AuditLog::with_file`) — sign + append + `fsync` per record: THE ceiling +//! (this is what a durable-custody deployment pays on the capability-use path). +//! +//! (2)/(1) is the price of durable custody per record; 1/µs_file is the single-writer durable +//! throughput ceiling the group-commit rewrite would lift. + +use std::time::Instant; + +use elastos_runtime::primitives::{AuditEvent, AuditLog, SecureTimestamp}; + +/// A minimal, allocation-light event so the measurement reflects the emit machinery +/// (sign + hash-chain + write), not event construction. +fn cheap_event() -> AuditEvent { + AuditEvent::RuntimeStart { + timestamp: SecureTimestamp::now(), + version: "bench".to_string(), + } +} + +fn bench_memory(iters: u64) -> f64 { + let log = AuditLog::new(); + let start = Instant::now(); + for _ in 0..iters { + log.emit(cheap_event()).expect("memory emit must succeed"); + } + start.elapsed().as_secs_f64() +} + +fn bench_file(iters: u64) -> f64 { + let dir = tempfile::tempdir().expect("tempdir"); + let log = AuditLog::with_file(dir.path().join("bench.log")).expect("file-backed log opens"); + let start = Instant::now(); + for _ in 0..iters { + log.emit(cheap_event()).expect("file emit must succeed"); + } + start.elapsed().as_secs_f64() +} + +/// The group-commit regime (S51): N threads hammer ONE file-backed log. Pre-S51 every emitter +/// serialized behind one fsync per record (total throughput pinned at the single-writer ceiling +/// regardless of thread count); with group commit, concurrent emits coalesce into shared fsyncs, +/// so total ops/s should scale well past that ceiling. Verifies the chain afterwards so the +/// number is for CORRECT commits only. +fn bench_file_concurrent(threads: u64, per_thread: u64) -> f64 { + let dir = tempfile::tempdir().expect("tempdir"); + let log = + std::sync::Arc::new(AuditLog::with_file(dir.path().join("bench.log")).expect("opens")); + let start = Instant::now(); + let handles: Vec<_> = (0..threads) + .map(|_| { + let log = log.clone(); + std::thread::spawn(move || { + for _ in 0..per_thread { + log.emit(cheap_event()).expect("concurrent emit succeeds"); + } + }) + }) + .collect(); + for h in handles { + h.join().expect("emitter thread"); + } + let secs = start.elapsed().as_secs_f64(); + // Verify under the log's REAL key (a signed chain refuses a keyless walk, fail-closed). + let vk_bytes: [u8; 32] = hex::decode(log.verifying_key_hex().expect("signed log")) + .expect("hex") + .try_into() + .expect("32 bytes"); + let vk = ed25519_dalek::VerifyingKey::from_bytes(&vk_bytes).expect("valid key"); + let verified = log + .verify_chain(Some(&vk)) + .expect("the concurrent chain must verify"); + assert_eq!( + verified, + threads * per_thread, + "no record lost or duplicated" + ); + secs +} + +fn report(label: &str, iters: u64, secs: f64) { + let ops = iters as f64 / secs; + let us = secs * 1_000_000.0 / iters as f64; + println!("{label:<30} {iters:>8} emits {secs:>7.3}s {ops:>12.0} ops/s {us:>9.2} us/op"); +} + +fn main() { + // Warm up (allocator, first-fsync, page cache) so the first timed regime isn't penalized. + let _ = bench_memory(1_000); + let _ = bench_file(200); + + let mem_iters: u64 = 200_000; + let file_iters: u64 = 20_000; // fewer: each performs a real fsync + + let mem_secs = bench_memory(mem_iters); + let file_secs = bench_file(file_iters); + + // Group-commit regime (S51): 8 concurrent emitters, one log. Pre-S51 this was pinned at the + // single-writer ceiling (every emitter serialized behind fsync-per-record); with group commit + // the coalesced fsyncs should push total ops/s well past it. + let conc_threads: u64 = 8; + let conc_per_thread: u64 = 2_500; + let conc_secs = bench_file_concurrent(conc_threads, conc_per_thread); + + println!("\n== audit emit throughput =="); + report("memory-only (new)", mem_iters, mem_secs); + report("file-backed (with_file/fsync)", file_iters, file_secs); + report( + "file-backed 8-thread (group)", + conc_threads * conc_per_thread, + conc_secs, + ); + + let mem_us = (mem_secs * 1e6 / mem_iters as f64).max(f64::MIN_POSITIVE); + let file_us = file_secs * 1e6 / file_iters as f64; + let single_ops = 1e6 / file_us; + let conc_ops = (conc_threads * conc_per_thread) as f64 / conc_secs; + println!( + "\ndurable-custody cost ~{:.1}x per record ({:.2} us -> {:.2} us); \ + single-writer durable ceiling ~{single_ops:.0} emits/s", + file_us / mem_us, + mem_us, + file_us, + ); + println!( + "group commit (S51): {conc_threads} concurrent emitters reach ~{conc_ops:.0} emits/s \ + ({:.1}x the single-writer ceiling; pre-S51 they were PINNED AT it — every emitter \ + serialized behind fsync-per-record)", + conc_ops / single_ops, + ); + println!( + "note: hardware- and filesystem-dependent (SSD vs HDD vs networked). Re-run on the target \ + box before relying on these magnitudes." + ); +} diff --git a/elastos/crates/elastos-runtime/src/capability/intent.rs b/elastos/crates/elastos-runtime/src/capability/intent.rs index b7dfe4d7..80636143 100644 --- a/elastos/crates/elastos-runtime/src/capability/intent.rs +++ b/elastos/crates/elastos-runtime/src/capability/intent.rs @@ -23,7 +23,7 @@ use std::collections::{BTreeSet, HashMap}; use std::sync::{Arc, RwLock}; use base64::{engine::general_purpose::STANDARD as BASE64, Engine}; -use ed25519_dalek::{Signature, Signer, SigningKey, Verifier, VerifyingKey}; +use ed25519_dalek::{Signature, Signer, SigningKey, VerifyingKey}; use serde::{Deserialize, Serialize}; use sha2::{Digest, Sha256}; @@ -49,6 +49,7 @@ const RECONCILE_SIG_DOMAIN: &[u8] = b"elastos.intent.reconciliation.v1\0"; /// declared arguments (same hashing path as the W2 binding), so the later receipt can be /// compared field-for-field. Signed exactly like [`AffordanceGrantReceiptV1`]. #[derive(Debug, Clone, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] pub struct IntentDeclarationV1 { pub schema: String, /// Stable id for this declaration (the reconciliation references it). @@ -74,6 +75,10 @@ pub struct IntentDeclarationV1 { } impl IntentDeclarationV1 { + /// The signature preimage. FROZEN: signer and verifier must hash identical bytes forever — + /// length-prefixed fields under a domain tag, then `declared_at` as its serde-JSON encoding. + /// That couples the preimage to [`SecureTimestamp`]'s JSON shape (field order/names in + /// `elastos-common`), which is therefore frozen too — a ratchet test pins the exact bytes. fn signable_digest(&self) -> [u8; 32] { let mut hasher = Sha256::new(); hasher.update(INTENT_SIG_DOMAIN); @@ -91,7 +96,10 @@ impl IntentDeclarationV1 { hasher.update((field.len() as u64).to_le_bytes()); hasher.update(field.as_bytes()); } - let ts = serde_json::to_vec(&self.declared_at).unwrap_or_default(); + // Serializing two u64 fields cannot fail; a silent empty-bytes fallback here would be a + // fail-OPEN idiom inside a signing path, so refuse loudly if the impossible happens. + let ts = serde_json::to_vec(&self.declared_at) + .expect("SecureTimestamp JSON encoding is infallible (two u64 fields)"); hasher.update((ts.len() as u64).to_le_bytes()); hasher.update(&ts); hasher.finalize().into() @@ -109,6 +117,36 @@ impl IntentDeclarationV1 { resource: &str, action: &str, standing_grant_id: &str, + ) -> Self { + Self::issue_at( + signing_key, + signer_pubkey, + intent_id, + capsule, + method_id, + input_hash, + resource, + action, + standing_grant_id, + SecureTimestamp::now(), + ) + } + + /// As [`issue`](Self::issue) but with an explicit `declared_at` — the signature covers it, so a + /// stale/future-dated declaration is authentic AND caught by [`check_intent_freshness`] (rather + /// than looking like a forgery). The freshness-window paths need this to be exercised. + #[allow(clippy::too_many_arguments)] + pub fn issue_at( + signing_key: &SigningKey, + signer_pubkey: [u8; 32], + intent_id: &str, + capsule: &str, + method_id: &str, + input_hash: &str, + resource: &str, + action: &str, + standing_grant_id: &str, + declared_at: SecureTimestamp, ) -> Self { let mut intent = Self { schema: INTENT_DECLARATION_SCHEMA_V1.to_string(), @@ -119,7 +157,7 @@ impl IntentDeclarationV1 { resource: resource.to_string(), action: action.to_string(), standing_grant_id: standing_grant_id.to_string(), - declared_at: SecureTimestamp::now(), + declared_at, signer: hex::encode(signer_pubkey), signature: String::new(), }; @@ -161,7 +199,24 @@ impl IntentDeclarationV1 { /// repeatedly with different arguments within the envelope (the whole point of /// unsupervised autonomy). Wiring this from a real issued `CapabilityToken` / grant is a /// later chunk; here it is the value the pure check consumes. -#[derive(Debug, Clone)] +/// Presence-required `Option` deserializer: the KEY must exist (serde's implicit +/// missing-`Option`-means-`None` is disabled by using `deserialize_with` without a default), and +/// an explicit `null` is an honest `None`. Guards the snapshot's two narrowing fields: a +/// hand-repaired file that DROPS `agent_pubkey` must not silently UNBIND an agent-bound mandate, +/// and one that drops `expires_at` must not immortalize it — the boot error invites the operator +/// to repair the file, so the repair path must be widen-proof, not just the happy path. +fn de_present_option<'de, D, T>(d: D) -> Result, D::Error> +where + D: serde::Deserializer<'de>, + T: Deserialize<'de>, +{ + Option::::deserialize(d) +} + +// `deny_unknown_fields` so a snapshot carrying fields this binary does not understand refuses to +// load (loud, fail-closed) instead of silently dropping semantics on a version rollback. +#[derive(Debug, Clone, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] pub struct StandingGrantEnvelope { pub grant_id: String, pub capsule: String, @@ -170,8 +225,56 @@ pub struct StandingGrantEnvelope { pub resource: String, pub action: String, /// Expiry; `None` = never expires (until revoked), mirroring `CapabilityToken::expiry`. + /// Presence-required on load: a snapshot missing the KEY is corrupt, never "never expires". + #[serde(deserialize_with = "de_present_option")] pub expires_at: Option, pub revoked: bool, + /// The AUTHORIZED AGENT's ed25519 verifying key (hex), if the grant bound one. When set, the + /// gate requires the intent to be signed by THIS key — so the mandate authorizes a specific + /// agent, and the audit attribution is the real actor, not "some self-signed key". `None` = + /// capsule-string-only authorization (weaker attribution; see KNOWN_GAPS G-M4). + /// Presence-required on load: a snapshot missing the KEY is corrupt, never an unbound mandate. + #[serde(deserialize_with = "de_present_option")] + pub agent_pubkey: Option, + /// The backing token's revocation epoch, captured at issue. A grant is dead once the runtime's + /// current epoch passes it (key rotation / revoke-all advance the epoch), so the dispatcher can + /// deny epoch-dead mandates without re-deriving the token. + pub token_epoch: u64, + /// The RESPONSIBLE ENTITY (Sprint 32): the operator/legal-entity DID accountable for every act + /// under this mandate — the working-registry mirror of the SIGNED custody in the grant's + /// `CapabilityGrant` chain event (the receipt is the proof; this field is the projection the + /// operator surfaces render). `#[serde(default)]` deliberately (unlike the presence-required + /// fields above): a pre-S32 snapshot honestly loads as `None` = "unrecorded", which weakens + /// nothing — the chain custody, not this mirror, is the liability artifact. + #[serde(default)] + pub responsible_entity: Option, + /// This mandate's own dispatch-rate budget (acts per [`MANDATE_DISPATCH_WINDOW_SECS`] window), + /// a first-class grant property (registry state, same trust level as `agent_pubkey` — not + /// signed into the token) added in Sprint 22. `None` = the global default + /// ([`MANDATE_DISPATCH_LIMIT`]); the mint refuses `Some(0)` and anything over + /// [`MANDATE_DISPATCH_LIMIT_MAX`]. Presence-required on load (like `agent_pubkey`/`expires_at`): + /// a v3 snapshot MISSING the key is refused, so an ACCIDENTAL key-drop / boot-repair cannot + /// silently reset an operator-tightened budget to the default. Honest bound: this does NOT stop + /// a same-disk attacker who rewrites the whole (unsigned) file — an explicit `"dispatch_limit": + /// null`, or a version-downgrade to v1/v2 (whose envelope legitimately has no such key), still + /// widens. That is the same same-disk caveat the snapshot carries throughout (closing it needs + /// the keyed-MAC roadmap item), not a property this field claims. + #[serde(deserialize_with = "de_present_option")] + pub dispatch_limit: Option, + /// When this grant was revoked (unix secs), if it has been (Sprint 23). Set by `revoke` / + /// `revoke_all`; `None` while live. Powers time-based RETENTION: a grant dead (revoked or + /// expired) longer than [`GRANT_RETENTION_SECS`] is pruned from the working registry — the audit + /// CHAIN keeps the grant/revoke/uses independently (the receipt is the permanent record; the + /// registry is only the working set), PROVIDED the mint's grant event landed on the chain (mint + /// audit is best-effort today — see KNOWN_GAPS G-M7). Unlike the narrowing fields above this is + /// `serde(default)`, NOT presence-required: a snapshot missing it loads as `None` = "unknown + /// revoke time → never TIME-prune → RETAIN", the fail-safe direction for the time stage (a + /// dropped key can only keep a grant longer against the CLOCK, never prune it early or widen + /// authority), so it needs no version bump or migration. (Under the hard CAP a `None` here keys + /// oldest-dead and is evicted first — but the cap only ever sheds already-DEAD grants, so this + /// changes eviction ORDER among the dead, never authority.) + #[serde(default)] + pub revoked_at: Option, } impl StandingGrantEnvelope { @@ -187,6 +290,21 @@ impl StandingGrantEnvelope { } } + /// The unix time this grant became DEAD, for retention (Sprint 23). `None` = either still live, + /// OR revoked without a recorded timestamp (a legacy grant — untimeable, so never TIME-pruned; + /// the hard cap can still evict it). A revoke times it via `revoked_at`; an expiry times it via + /// `expires_at`. Revocation (the explicit kill) wins when both apply. + fn dead_since(&self) -> Option { + if self.is_active() { + return None; + } + if self.revoked { + return self.revoked_at; + } + // Inactive and not revoked ⇒ expired, so `expires_at` is necessarily `Some`. + self.expires_at.map(|e| e.unix_secs) + } + /// Derive a standing envelope from a real issued [`CapabilityToken`] (chunk 3): the /// token supplies the authority that is actually signed into it — `capsule`, /// `resource`, `action`, and `expiry`. The token does NOT enumerate affordance @@ -198,6 +316,9 @@ impl StandingGrantEnvelope { token: &CapabilityToken, allowed_methods: BTreeSet, revoked: bool, + agent_pubkey: Option, + dispatch_limit: Option, + responsible_entity: Option, ) -> Self { StandingGrantEnvelope { grant_id: token.id().to_string(), @@ -207,6 +328,11 @@ impl StandingGrantEnvelope { action: token.action().to_string(), expires_at: token.expiry().copied(), revoked, + agent_pubkey: agent_pubkey.map(|k| k.trim().to_lowercase()), + token_epoch: token.constraints().epoch(), + dispatch_limit, + revoked_at: None, + responsible_entity, } } } @@ -218,6 +344,8 @@ pub enum EnvelopeDenial { Revoked, Expired, WrongCapsule, + /// The intent was signed by a key other than the mandate's bound agent key. + WrongAgent, MethodNotInEnvelope, WrongResource, WrongAction, @@ -234,6 +362,7 @@ impl EnvelopeDenial { EnvelopeDenial::Revoked => "revoked", EnvelopeDenial::Expired => "expired", EnvelopeDenial::WrongCapsule => "wrong_capsule", + EnvelopeDenial::WrongAgent => "wrong_agent", EnvelopeDenial::MethodNotInEnvelope => "method_not_in_envelope", EnvelopeDenial::WrongResource => "wrong_resource", EnvelopeDenial::WrongAction => "wrong_action", @@ -268,6 +397,16 @@ pub fn check_intent_within_envelope( if intent.capsule != envelope.capsule { return EnvelopeCheck::Denied(EnvelopeDenial::WrongCapsule); } + // Agent-key binding: if the mandate bound a specific agent key, ONLY that key may act under it. + // `verify_self` already proved the declaration was signed by the key it names (`intent.signer`); + // this proves that key is the AUTHORIZED agent, so the audit attribution is the real actor and + // a different self-signed key cannot borrow the mandate. A mandate with no bound key (`None`) + // stays capsule-string-only — weaker attribution, tracked in KNOWN_GAPS G-M4. + if let Some(agent) = &envelope.agent_pubkey { + if !intent.signer.trim().eq_ignore_ascii_case(agent) { + return EnvelopeCheck::Denied(EnvelopeDenial::WrongAgent); + } + } if !envelope.allowed_methods.contains(&intent.method_id) { return EnvelopeCheck::Denied(EnvelopeDenial::MethodNotInEnvelope); } @@ -291,8 +430,11 @@ pub enum ReconciliationStatus { /// A receipt exists but a bound field differs from the declared intent (the act fired /// within the envelope, but not as declared — flagged, never masked). Diverged, - /// The intent was declared but no receipt was produced (the act never completed). - /// Absence is recorded, never a silent pass. + /// The intent was declared but no receipt was produced. This is ABSENCE OF ATTESTATION, not + /// proof the act never happened (council S29 F5): for a side-effecting executor whose outcome + /// is INDETERMINATE (e.g. a payment rail timeout — the effect may have landed), this is the + /// deliberately honest verdict — nothing attests performance, so nothing claims it. Absence is + /// recorded, never a silent pass; the executor's decline reason carries the specifics. Undelivered, } @@ -364,6 +506,8 @@ pub struct IntentReconciliationV1 { } impl IntentReconciliationV1 { + /// FROZEN preimage — same rules (and the same `SecureTimestamp` JSON coupling) as + /// [`IntentDeclarationV1::signable_digest`]. fn signable_digest(&self) -> [u8; 32] { let mut hasher = Sha256::new(); hasher.update(RECONCILE_SIG_DOMAIN); @@ -378,7 +522,9 @@ impl IntentReconciliationV1 { hasher.update((field.len() as u64).to_le_bytes()); hasher.update(field.as_bytes()); } - let ts = serde_json::to_vec(&self.reconciled_at).unwrap_or_default(); + // Infallible for two u64 fields; never silently hash empty bytes in a signing path. + let ts = serde_json::to_vec(&self.reconciled_at) + .expect("SecureTimestamp JSON encoding is infallible (two u64 fields)"); hasher.update((ts.len() as u64).to_le_bytes()); hasher.update(&ts); hasher.finalize().into() @@ -424,7 +570,12 @@ fn verify_b64_sig(signature_b64: &str, digest: &[u8; 32], verifying_key: &Verify Err(_) => return false, }; let signature = Signature::from_bytes(&sig_arr); - verifying_key.verify(digest, &signature).is_ok() + // STRICT verification (council, Sprint 20 red-team F1): `verify` (non-strict) accepts low-order + // / identity verifying keys, for which a forged signature validates for ANY message. A mandate + // "bound" to such a key would be satisfiable by anyone — an effectively-UNBOUND mandate wearing + // a "bound" badge. `verify_strict` rejects small-order keys + non-canonical signatures, closing + // it at the gate everywhere (not just at mint), the security-correct default for authenticity. + verifying_key.verify_strict(digest, &signature).is_ok() } // ─────────────────────────── On-chain custody events (chunk 2) ──────────────── @@ -623,6 +774,57 @@ where // CapabilityManager owns token revocation. Kept deliberately small and fail-closed so an // agent can only ever run under a grant that was issued and is still live. +/// The oldest a dispatched intent's `declared_at` may be and still act — a captured signed +/// declaration EXPIRES after this, so it cannot be replayed indefinitely, and the replay guard +/// only has to remember intents this recent (bounding its size; G-M7). NOTE (clock trust): the +/// freshness window + compaction trust the host `SystemTime::now()` — the same custody class as the +/// same-disk snapshot caveat. A bad clock fails CLOSED (rejects, never over-admits): a backward +/// jump can spuriously reject valid intents, a forward jump compacts+rejects more, and neither +/// enables a double-act (the first act's id sits in the seen-set, which a rewind does not compact). +pub const MAX_INTENT_AGE_SECS: u64 = 3600; // 1 hour +/// How far in the FUTURE an intent's `declared_at` may be (clock skew) before it is refused — a +/// far-future date is either a badly-skewed clock or a forgery reaching for a longer replay life. +pub const MAX_CLOCK_SKEW_SECS: u64 = 300; // 5 minutes +/// The replay guard keeps a seen id until its `declared_at` ages past the whole acceptance window +/// (age + skew): while an intent could still pass the freshness check it MUST stay remembered, and +/// once it can no longer pass, forgetting it opens no replay (freshness rejects any re-POST). This +/// margin — RETENTION strictly greater than the max accepted age by exactly the skew term — is +/// load-bearing: it is why a compacted id is ALWAYS freshness-rejected on replay. +pub const SEEN_INTENT_RETENTION_SECS: u64 = MAX_INTENT_AGE_SECS + MAX_CLOCK_SKEW_SECS; + +/// Why a dispatched intent failed the freshness window — the fail-closed reasons the dispatcher +/// records/returns before consulting the replay guard. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum FreshnessError { + /// `declared_at` is older than [`MAX_INTENT_AGE_SECS`] — the declaration has expired. + Stale, + /// `declared_at` is more than [`MAX_CLOCK_SKEW_SECS`] in the future. + FutureDated, +} + +impl FreshnessError { + pub fn as_str(self) -> &'static str { + match self { + FreshnessError::Stale => "intent_declaration_expired", + FreshnessError::FutureDated => "intent_declaration_future_dated", + } + } +} + +/// Fail-closed freshness gate for a dispatched intent: `declared_at` must sit within +/// `[now - MAX_INTENT_AGE_SECS, now + MAX_CLOCK_SKEW_SECS]`. This bounds how long a captured +/// declaration can be replayed AND lets the replay guard forget anything older than the window +/// (G-M7). Pure over its two `u64` unix-second inputs, so it is trivially testable. +pub fn check_intent_freshness(declared_at_secs: u64, now_secs: u64) -> Result<(), FreshnessError> { + if declared_at_secs > now_secs.saturating_add(MAX_CLOCK_SKEW_SECS) { + return Err(FreshnessError::FutureDated); + } + if declared_at_secs < now_secs.saturating_sub(MAX_INTENT_AGE_SECS) { + return Err(FreshnessError::Stale); + } + Ok(()) +} + /// A fail-closed registry of [`StandingGrantEnvelope`]s for unsupervised agent dispatch, /// keyed by `grant_id`. Every mutation is a single locked statement, so the map is never /// observed half-updated. Fail-closed by construction: @@ -635,41 +837,481 @@ where #[derive(Default)] pub struct StandingGrantStore { grants: RwLock>, + /// Intent ids already dispatched → their `declared_at` (unix secs) — the replay guard. A + /// standing mandate is deliberately multi-use (the agent may act repeatedly with DIFFERENT + /// intents), but the SAME signed declaration must act at most once, or a captured/retried blob + /// is a double-act. With a persistent store the map survives restart (G-M5); it is COMPACTED + /// against the freshness window on every write, so it is bounded, not monotonic (G-M7). The + /// stored `declared_at` is what compaction ages against. + seen_intents: RwLock>, + /// The highest `declared_at` ever COMPACTED out of `seen_intents` — a persisted anti-readmit + /// watermark. Compaction forgets aged ids to stay bounded, which (red-team, Sprint 19) would + /// otherwise let a captured intent be REPLAYED after a BACKWARD wall-clock step (evicted while + /// the clock was high, then re-POSTed after the clock rewinds into its freshness window). An + /// intent whose `declared_at <= max_evicted` was, or is shadowed by, an already-forgotten + /// dispatch, so it is refused as a replay — clock-direction-independent, unlike the freshness + /// window alone. Monotonic non-decreasing; guarded by the `seen_intents` write lock. + max_evicted_declared_at: std::sync::atomic::AtomicU64, + /// Per-mandate dispatch RATE budget (G-M7): `grant_id → (window_start_secs, count_in_window)`. + /// Each mandate may perform at most [`MANDATE_DISPATCH_LIMIT`] acts per + /// [`MANDATE_DISPATCH_WINDOW_SECS`], so a mandate-holding agent cannot flood dispatch (each act + /// otherwise costs a durable snapshot write + fsync). In-memory: a restart refills the budget, + /// which is the safe/generous direction (never a spurious denial), and the agent cannot restart + /// the runtime. Bounded two ways: elapsed windows are pruned when the map grows, AND a HARD CAP + /// (`DISPATCH_RATE_SOFT_CAP`) refuses new keys once reached — so even a same-window flood of + /// distinct grant_ids cannot grow it without bound. In the dispatch path the handler also refuses + /// unknown grant_ids before this is ever reached, so only real, operator-issued grant_ids land + /// here at all. + dispatch_rate: RwLock>, + /// Snapshot file for a PERSISTENT registry (`None` = memory-only). Every mutation writes the + /// full snapshot atomically (temp + fsync + rename, mirroring `CapabilityStore`) BEFORE the + /// change becomes visible — on a write failure the mutation is rolled back and the error + /// surfaces, so disk and memory can never diverge (no crash-revived mandate, no crash-forgotten + /// revoke, no crash-forgotten replay guard). + storage_path: Option, +} + +/// The most dispatch acts a single mandate may perform per [`MANDATE_DISPATCH_WINDOW_SECS`] — the +/// per-mandate rate budget (G-M7). Generous for a real agent (1/sec average, burstable), but bounds +/// a flood: an agent cannot make its mandate perform unbounded acts (each act is a durable write). +pub const MANDATE_DISPATCH_LIMIT: u32 = 60; +/// The rolling window (seconds) the per-mandate dispatch budget is measured over. +pub const MANDATE_DISPATCH_WINDOW_SECS: u64 = 60; +/// The largest per-mandate dispatch budget the mint will accept (Sprint 22 council, red-team F2 / +/// guardian F3). A per-mandate `dispatch_limit` above this is refused — not a security boundary (a +/// grant-root operator can already raise aggregate rate by minting more mandates, so this adds no +/// authority class), but a footgun stop: without it a single mandate dialed to `u32::MAX` would +/// linearly uncap the durable-write (fsync) flood the budget exists to bound. Generous for any real +/// agent (many acts/second sustained), so a tighter operational limit stays an operator choice. +pub const MANDATE_DISPATCH_LIMIT_MAX: u32 = 3600; +/// The dispatch-rate map's bound. When it exceeds this, elapsed windows are pruned; if it is still +/// at/over the cap a NEW key is then refused (hard cap) — so an attacker spamming DISTINCT (even +/// non-existent) grant_ids cannot grow it without bound, even within a single window. +const DISPATCH_RATE_SOFT_CAP: usize = 4096; + +/// How long a DEAD (revoked or expired) mandate is retained in the working registry before it is +/// pruned (Sprint 23, closes G-M7). Generous — 30 days — so an operator sees recently-killed +/// mandates on the card long after the fact; the audit CHAIN keeps the grant/revoke/uses forever +/// (the receipt is the permanent record), so pruning the working-set entry erases nothing provable. +/// Only DEAD grants age out; a live mandate is never pruned by time. +pub const GRANT_RETENTION_SECS: u64 = 30 * 24 * 60 * 60; +/// The working registry's hard cap (Sprint 23). After the time-retention prune, if the map is still +/// over this, the OLDEST-dead grants are evicted until at cap — never a live one. Bounds the +/// accumulation G-M7 flagged (dead grants piling up); a live set larger than this is operator-real +/// authority (bounded by real issuance, like any resource), never shed to satisfy the cap. +const REGISTRY_HARD_CAP: usize = 4096; + +/// The on-disk snapshot of the standing-grant registry, version-pinned. Same-disk custody caveat +/// as the audit log's head-anchor: this defends against loss/corruption (strict parse, fail-closed +/// boot), not against a root attacker rewriting the file — that adversary already owns the runtime +/// key material on the same disk. Honest bound on "strict": the parse catches STRUCTURAL damage +/// (truncation, wrong version, unknown fields via `deny_unknown_fields`); a semantically-valid +/// same-disk edit that DROPS an `Option` field (e.g. deleting `agent_pubkey` to unbind an +/// agent-bound mandate — serde defaults a missing `Option` to `None`) is inside the same-disk +/// caveat, not caught here. Making well-formed edits detectable needs a keyed MAC (roadmap, same +/// custody class as the head-anchor co-signing). +/// One remembered intent id + the `declared_at` (unix secs) compaction ages it against. +#[derive(Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +struct SeenIntentRecord { + id: String, + declared_at: u64, +} + +/// The current (v3) snapshot: envelopes carry the per-mandate `dispatch_limit` +/// (presence-required — Sprint 22), and the replay guard stores `declared_at` per id so the +/// seen-set can be compacted against the freshness window (bounded, not monotonic — G-M7). +#[derive(Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +struct StandingGrantSnapshotV3 { + version: u32, + grants: Vec, + seen_intents: Vec, + /// The anti-readmit watermark (see [`StandingGrantStore::max_evicted_declared_at`]). `default` + /// so a file written before this field existed loads as 0 (no watermark yet — safe, the + /// remembered ids still guard replay until they age, at which point the watermark takes over). + #[serde(default)] + max_evicted_declared_at: u64, +} + +/// The envelope shape persisted by snapshot v1/v2 — before per-mandate dispatch budgets existed. +/// Read for a one-time MIGRATION only (never written): `dispatch_limit` becomes `None` (the global +/// default), which is exactly the budget those mandates were enforced under when written — the +/// migration neither widens nor tightens any grant. +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct LegacyStandingGrantEnvelope { + grant_id: String, + capsule: String, + allowed_methods: BTreeSet, + resource: String, + action: String, + #[serde(deserialize_with = "de_present_option")] + expires_at: Option, + revoked: bool, + #[serde(deserialize_with = "de_present_option")] + agent_pubkey: Option, + token_epoch: u64, } +impl From for StandingGrantEnvelope { + fn from(l: LegacyStandingGrantEnvelope) -> Self { + StandingGrantEnvelope { + grant_id: l.grant_id, + capsule: l.capsule, + allowed_methods: l.allowed_methods, + resource: l.resource, + action: l.action, + expires_at: l.expires_at, + revoked: l.revoked, + agent_pubkey: l.agent_pubkey, + token_epoch: l.token_epoch, + dispatch_limit: None, + // A legacy (pre-S32) grant recorded no responsible entity — honest None, never guessed. + responsible_entity: None, + // A legacy grant carries no revoke timestamp; None = never time-prune (retain). If it + // was revoked, it stays queryable-as-revoked and only the hard cap can ever shed it. + revoked_at: None, + } + } +} + +/// The prior (v2) snapshot: same shape as v3 but its envelopes predate `dispatch_limit`. Read for +/// a one-time MIGRATION (never written). +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct StandingGrantSnapshotV2 { + #[allow(dead_code)] + version: u32, + grants: Vec, + seen_intents: Vec, + #[serde(default)] + max_evicted_declared_at: u64, +} + +/// The oldest (v1) snapshot: seen intents were bare ids with no timestamp. Read for a one-time +/// MIGRATION (never written): its ids are re-stamped `declared_at = load time` so they age out one +/// full window after upgrade — conservative (remembered longer, never a replay window). +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct StandingGrantSnapshotV1 { + #[allow(dead_code)] + version: u32, + grants: Vec, + seen_intents: Vec, +} + +const STANDING_GRANT_SNAPSHOT_VERSION: u32 = 3; + impl StandingGrantStore { pub fn new() -> Self { Self::default() } - /// Issue (or replace) a standing grant, keyed by its `grant_id`. Issuing an envelope whose - /// `revoked` flag is already set stores it as revoked (authorizes nothing) — issuing never - /// silently un-revokes a grant. - pub fn issue(&self, envelope: StandingGrantEnvelope) { + /// Open (or create) a PERSISTENT registry backed by a snapshot file — mandates and the replay + /// guard survive restart. STRICT load, fail-closed at boot: a present-but-unparseable (or + /// wrong-version) file is an error, never silently skipped — a skipped record could resurrect + /// a revoked mandate or forget a dispatched intent (a replay window). A missing file is a + /// clean first boot. + pub fn with_persistence(path: impl AsRef) -> std::io::Result { + let path = path.as_ref().to_path_buf(); + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent)?; + } + let store = Self { + storage_path: Some(path.clone()), + ..Self::default() + }; + if path.exists() { + let content = std::fs::read_to_string(&path)?; + let invalid = |e: String| { + std::io::Error::new( + std::io::ErrorKind::InvalidData, + format!( + "standing-grant registry at {} is unreadable ({e}); refusing to boot over \ + corrupt mandate state — repair or remove the file explicitly", + path.display() + ), + ) + }; + // Probe the version first so a v1 file can be MIGRATED rather than fail-closed-refused + // (refusing would drop every mandate + the replay guard on upgrade). Any other version + // is still refused, and structural corruption in EITHER shape is refused. + let version = serde_json::from_str::(&content) + .ok() + .and_then(|v| v.get("version").and_then(|n| n.as_u64())) + .ok_or_else(|| invalid("missing/invalid version".to_string()))?; + #[allow(clippy::type_complexity)] + let (grants_in, seen_in, max_evicted): ( + Vec, + Vec<(String, u64)>, + u64, + ) = match version { + 3 => { + let s: StandingGrantSnapshotV3 = + serde_json::from_str(&content).map_err(|e| invalid(e.to_string()))?; + let seen = s + .seen_intents + .into_iter() + .map(|r| (r.id, r.declared_at)) + .collect(); + (s.grants, seen, s.max_evicted_declared_at) + } + 2 => { + // MIGRATION: v2 envelopes predate `dispatch_limit`; they load as `None` (the + // global default) — the exact budget they were enforced under when written. + let s: StandingGrantSnapshotV2 = + serde_json::from_str(&content).map_err(|e| invalid(e.to_string()))?; + let seen = s + .seen_intents + .into_iter() + .map(|r| (r.id, r.declared_at)) + .collect(); + let grants = s.grants.into_iter().map(Into::into).collect(); + (grants, seen, s.max_evicted_declared_at) + } + 1 => { + // MIGRATION: re-stamp legacy bare ids with the load time so they age out one + // full window from now — never a replay window (a re-POST of an old intent is + // caught while remembered, and rejected by freshness/watermark once forgotten). + // No v1 watermark existed; 0 is safe (remembered ids guard until they age, then + // the watermark starts tracking their eviction). + let s: StandingGrantSnapshotV1 = + serde_json::from_str(&content).map_err(|e| invalid(e.to_string()))?; + let now = SecureTimestamp::now().unix_secs; + let seen = s.seen_intents.into_iter().map(|id| (id, now)).collect(); + let grants = s.grants.into_iter().map(Into::into).collect(); + (grants, seen, 0) + } + other => { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidData, + format!( + "standing-grant registry at {} has unsupported version {} \ + (expected {})", + path.display(), + other, + STANDING_GRANT_SNAPSHOT_VERSION + ), + )); + } + }; + let mut grants = match store.grants.write() { + Ok(g) => g, + Err(poisoned) => poisoned.into_inner(), + }; + for env in grants_in { + grants.insert(env.grant_id.clone(), env); + } + drop(grants); + let mut seen = match store.seen_intents.write() { + Ok(s) => s, + Err(poisoned) => poisoned.into_inner(), + }; + seen.extend(seen_in); + store + .max_evicted_declared_at + .store(max_evicted, std::sync::atomic::Ordering::SeqCst); + drop(seen); + // Bound a file that grew under an OLDER binary (Sprint 23): prune dead-past-retention + + // over-cap grants on boot, then rewrite the shrunk snapshot. Best-effort — if the + // rewrite fails the pruned entries simply persist on disk and re-prune next mutation / + // boot (disk-holds-extra-dead is harmless, never a lost revoke or a revived mandate). + let now = SecureTimestamp::now().unix_secs; + let mut grants = match store.grants.write() { + Ok(g) => g, + Err(poisoned) => poisoned.into_inner(), + }; + let pruned = Self::prune_registry_locked(&mut grants, now, ""); + if !pruned.is_empty() { + let seen = match store.seen_intents.write() { + Ok(s) => s, + Err(poisoned) => poisoned.into_inner(), + }; + let _ = store.persist_locked(&grants, &seen); + } + } + Ok(store) + } + + /// Prune the working registry (Sprint 23, closes G-M7), returning the removed entries so the + /// caller can ROLL BACK on a persist failure. Runs under the grants write guard. Two stages, + /// both of which NEVER remove a live grant and never the `exempt` id (the one just issued): + /// 1. TIME RETENTION — drop grants dead (revoked/expired) longer than [`GRANT_RETENTION_SECS`]. + /// 2. HARD CAP — if the map is STILL over [`REGISTRY_HARD_CAP`], evict the OLDEST-dead grants + /// (revoked-untimeable ones first, keyed dead-time 0) until at cap. If everything over the + /// cap is LIVE, the map stays over cap — a live mandate is operator-real authority, never + /// shed to satisfy a bound; the cap exists to reclaim DEAD accumulation, the G-M7 vector. + /// + /// The audit CHAIN keeps every grant/revoke/use — pruning the working set erases nothing + /// provable (the receipt is the permanent record; this is the working set), PROVIDED the mint's + /// grant event landed on the chain (mint audit is best-effort; a mint whose audit append failed + /// has no trace independent of the registry — KNOWN_GAPS G-M7, fail-closed mint is the tracked + /// fix). Time-death is WALL-CLOCK: a backward clock makes a grant look less-dead (retained — + /// safe); a forward excursion beyond the 30-day window could prune a live-but-recently-expiring + /// mandate — a bound shared with expiry itself (a clock-jumped mandate already denies), not + /// cleanly clampable without a trusted external clock we do not have. + fn prune_registry_locked( + grants: &mut HashMap, + now_secs: u64, + exempt: &str, + ) -> Vec<(String, StandingGrantEnvelope)> { + let mut removed = Vec::new(); + // Stage 1: time retention — a grant dead longer than the window ages out. + let aged: Vec = grants + .iter() + .filter(|(id, _)| id.as_str() != exempt) + .filter_map(|(id, env)| { + env.dead_since() + .filter(|t| now_secs >= t.saturating_add(GRANT_RETENTION_SECS)) + .map(|_| id.clone()) + }) + .collect(); + for id in aged { + if let Some(env) = grants.remove(&id) { + removed.push((id, env)); + } + } + // Stage 2: hard cap — shed the oldest DEAD grants (never a live one) until at cap. + if grants.len() > REGISTRY_HARD_CAP { + let mut dead: Vec<(u64, String)> = grants + .iter() + .filter(|(id, env)| id.as_str() != exempt && !env.is_active()) + .map(|(id, env)| (env.dead_since().unwrap_or(0), id.clone())) + .collect(); + dead.sort(); // oldest-dead (smallest dead-time, then id) first + let overflow = grants.len() - REGISTRY_HARD_CAP; + for (_, id) in dead.into_iter().take(overflow) { + if let Some(env) = grants.remove(&id) { + removed.push((id, env)); + } + } + } + removed + } + + /// Write the full snapshot atomically (temp + fsync + rename). Called with BOTH write guards + /// held so the serialized state is exactly the state that becomes visible. Memory-only ⇒ no-op. + fn persist_locked( + &self, + grants: &HashMap, + seen: &HashMap, + ) -> std::io::Result<()> { + let Some(path) = &self.storage_path else { + return Ok(()); + }; + let mut grant_list: Vec = grants.values().cloned().collect(); + grant_list.sort_by(|a, b| a.grant_id.cmp(&b.grant_id)); + let mut seen_list: Vec = seen + .iter() + .map(|(id, declared_at)| SeenIntentRecord { + id: id.clone(), + declared_at: *declared_at, + }) + .collect(); + seen_list.sort_by(|a, b| a.id.cmp(&b.id)); + let snapshot = StandingGrantSnapshotV3 { + version: STANDING_GRANT_SNAPSHOT_VERSION, + grants: grant_list, + seen_intents: seen_list, + max_evicted_declared_at: self + .max_evicted_declared_at + .load(std::sync::atomic::Ordering::SeqCst), + }; + let content = serde_json::to_vec(&snapshot) + .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?; + let tmp_path = path.with_extension("tmp"); + { + use std::io::Write as _; + let mut tmp = std::fs::File::create(&tmp_path)?; + tmp.write_all(&content)?; + // Durable BEFORE visible: the rename must never publish bytes still in the page cache. + tmp.sync_all()?; + } + std::fs::rename(&tmp_path, path)?; + // DURABLE rename (red-team F1): without fsyncing the parent directory, a power cut after + // the rename can revert the directory entry to the OLD snapshot — atomic but not yet + // durable. For the replay guard that revert IS a replay window (a captured signed intent + // acts twice), so the fsync is part of the write, not a nicety. If THIS fsync fails the + // rename has already landed: the caller still rolls back memory and surfaces the error — + // disk then holds the newer snapshot, which reconciles at the next successful mutation or + // restart, and the disk-ahead direction never loses a revoke or a seen intent. + #[cfg(unix)] + if let Some(parent) = path.parent() { + std::fs::File::open(parent)?.sync_all()?; + } + Ok(()) + } + + /// Issue (or replace) a standing grant, keyed by its `grant_id`, durable-before-visible. + /// Issuing an envelope whose `revoked` flag is already set stores it as revoked (authorizes + /// nothing) — issuing never silently un-revokes a grant. On a persistence failure the issuance + /// is rolled back and the error surfaces: a mandate that cannot survive a restart is not + /// issued at all (fail-closed, mirroring the manager's emit-before-mutate revoke). + pub fn issue(&self, envelope: StandingGrantEnvelope) -> std::io::Result<()> { let mut grants = match self.grants.write() { Ok(g) => g, // A poisoned lock can only mean a prior panic; every write is one statement, so the // map is structurally intact — recover the guard rather than drop the issuance. Err(poisoned) => poisoned.into_inner(), }; - grants.insert(envelope.grant_id.clone(), envelope); + let seen = match self.seen_intents.write() { + Ok(s) => s, + Err(poisoned) => poisoned.into_inner(), + }; + let grant_id = envelope.grant_id.clone(); + let previous = grants.insert(grant_id.clone(), envelope); + // Bound the working registry AT the growth point (Sprint 23): the just-issued grant is + // exempt (never pruned, even if issued already-dead), so issuance always succeeds while + // dead accumulation is reclaimed. Persist ONCE with the pruned state. + let now = SecureTimestamp::now().unix_secs; + let pruned = Self::prune_registry_locked(&mut grants, now, &grant_id); + if let Err(e) = self.persist_locked(&grants, &seen) { + // Roll back: disk is the durable truth; memory must not run ahead of it. Restore the + // pruned entries AND undo the insert, so a failed write leaves the map exactly as it was. + for (id, env) in pruned { + grants.insert(id, env); + } + match previous { + Some(prev) => grants.insert(grant_id, prev), + None => grants.remove(&grant_id), + }; + return Err(e); + } + Ok(()) } - /// Revoke a standing grant by id, fail-closed. Returns `true` iff a live (not-already-revoked) - /// grant was revoked by THIS call — so a double-revoke or an unknown id returns `false`. The - /// record is retained with `revoked = true` so the grant stays queryable as revoked. - pub fn revoke(&self, grant_id: &str) -> bool { + /// Revoke a standing grant by id, fail-closed AND durable-before-visible. Returns `true` iff a + /// live (not-already-revoked) grant was revoked by THIS call — a double-revoke or an unknown id + /// returns `false`. The record is retained with `revoked = true` so the grant stays queryable + /// as revoked. On a persistence failure the flag is rolled back and the error surfaces — a + /// revoke that would crash-revive on restart does not report success. + pub fn revoke(&self, grant_id: &str) -> std::io::Result { let mut grants = match self.grants.write() { Ok(g) => g, Err(poisoned) => poisoned.into_inner(), }; + let seen = match self.seen_intents.write() { + Ok(s) => s, + Err(poisoned) => poisoned.into_inner(), + }; + let now = SecureTimestamp::now().unix_secs; match grants.get_mut(grant_id) { Some(env) if !env.revoked => { env.revoked = true; - true + // Stamp the revoke time so retention can age this dead grant out (Sprint 23). + env.revoked_at = Some(now); + } + _ => return Ok(false), + } + if let Err(e) = self.persist_locked(&grants, &seen) { + if let Some(env) = grants.get_mut(grant_id) { + env.revoked = false; + env.revoked_at = None; } - _ => false, + return Err(e); } + Ok(true) } /// The standing grant for `grant_id`, if one was ever issued (revoked or not). The dispatcher @@ -681,6 +1323,216 @@ impl StandingGrantStore { grants.get(grant_id).cloned() } + /// Every standing grant ever issued this runtime lifetime (revoked ones INCLUDED, flagged — + /// an operator surface must show what was killed, not erase it), sorted by `grant_id` for a + /// stable listing. Read-only. A poisoned lock recovers via `into_inner()` exactly like the + /// writes do (every write is one statement, so the map is structurally intact): the operator + /// surface must NEVER render a fabricated-clean "no mandates" over a map that has entries. + pub fn list(&self) -> Vec { + let grants = match self.grants.read() { + Ok(g) => g, + Err(poisoned) => poisoned.into_inner(), + }; + let mut all: Vec = grants.values().cloned().collect(); + all.sort_by(|a, b| a.grant_id.cmp(&b.grant_id)); + all + } + + /// The dispatch-rate budget ENFORCED for `grant_id`: the mandate's own `dispatch_limit` when it + /// set one, else the global [`MANDATE_DISPATCH_LIMIT`]. Read from the registry (trusted state) — + /// the single resolver used by both enforcement and the over-budget message, so the number the + /// gate enforces and the number it reports can never diverge (council F1, P12). An unknown + /// grant_id resolves to the default (in the dispatch path the handler screens unknown ids first). + pub fn dispatch_limit_for(&self, grant_id: &str) -> u32 { + let grants = match self.grants.read() { + Ok(g) => g, + Err(poisoned) => poisoned.into_inner(), + }; + grants + .get(grant_id) + .and_then(|env| env.dispatch_limit) + .unwrap_or(MANDATE_DISPATCH_LIMIT) + } + + /// Record a dispatch against the per-mandate RATE budget (G-M7): returns `true` iff this + /// mandate is WITHIN its budget for the current [`MANDATE_DISPATCH_WINDOW_SECS`] window (and + /// counts this attempt), `false` if it is over budget. The limit is the mandate's OWN + /// `dispatch_limit` when the grant set one (Sprint 22 — rate is a first-class grant property, + /// resolved HERE from the registry so no caller can pass a wrong limit), else the global + /// [`MANDATE_DISPATCH_LIMIT`]. The dispatcher calls this AFTER authenticity + freshness (so + /// only well-formed fresh intents count) and BEFORE the replay guard's durable write, so a + /// flood is rejected before it + /// costs an fsync. In-memory + bounded: a stale window resets on access, the map is pruned of + /// elapsed windows when it grows past the soft cap, and a HARD CAP then refuses NEW keys while at + /// capacity — so even a same-window flood of distinct (even fake) grant_ids cannot grow it + /// without bound (an existing key is always still counted, so a real mandate is never denied by + /// the cap). A poisoned lock recovers via `into_inner()` (fail-safe: a recovered map is + /// structurally intact). + pub fn record_dispatch_within_budget(&self, grant_id: &str, now_secs: u64) -> bool { + // Resolve the mandate's own budget first (registry read lock released before the rate + // lock — no nesting). ONE resolver, shared with the 429 message, so what the gate enforces + // and what it REPORTS can never diverge (council F1, P12). + let limit = self.dispatch_limit_for(grant_id); + // The mint refuses `Some(0)`, so a zero here means a tampered/corrupt registry entry — + // fail closed (deny every act) rather than let the window-reset branch admit one per window. + if limit == 0 { + return false; + } + let mut rate = match self.dispatch_rate.write() { + Ok(r) => r, + Err(poisoned) => poisoned.into_inner(), + }; + // Bound memory in two steps. First drop windows that have FULLY ELAPSED (they would reset + // on next access anyway) — this reclaims across-window entries. + if rate.len() > DISPATCH_RATE_SOFT_CAP { + rate.retain(|_, (window_start, _)| { + now_secs < window_start.saturating_add(MANDATE_DISPATCH_WINDOW_SECS) + }); + // Then a HARD CAP for the within-a-single-window case the prune above cannot help: + // inside one window every entry is non-stale, so `retain` reclaims nothing and a + // distinct-grant_id flood would otherwise grow the map without bound. Once we are STILL + // at/over the cap after pruning, refuse a NEW (unseen) grant_id — return false, i.e. + // over-budget → 429. An EXISTING grant_id keeps its entry and is counted normally, so a + // real mandate is never denied by the cap; only never-before-seen keys are shed. The + // map is thus hard-bounded at ~DISPATCH_RATE_SOFT_CAP. Fail-closed. (In the dispatch + // path the handler's grant-existence check already ensures only real grant_ids arrive, + // so this is belt-and-suspenders that also makes this method bounded when called alone.) + if rate.len() >= DISPATCH_RATE_SOFT_CAP && !rate.contains_key(grant_id) { + return false; + } + } + let entry = rate.entry(grant_id.to_string()).or_insert((now_secs, 0)); + if now_secs >= entry.0.saturating_add(MANDATE_DISPATCH_WINDOW_SECS) { + // A new window — reset and count this act. + *entry = (now_secs, 1); + return true; + } + if entry.1 < limit { + entry.1 += 1; + return true; + } + false + } + + /// Whether ANY dispatch-rate entry exists. Test observability: proves a distinct-fake-grant_id + /// flood created no rate entries (the handler's existence check ran before the budget). + pub fn any_dispatch_rate_entries(&self) -> bool { + match self.dispatch_rate.read() { + Ok(r) => !r.is_empty(), + Err(poisoned) => !poisoned.into_inner().is_empty(), + } + } + + /// Register an intent id as dispatched, returning `true` iff it was FRESH. The replay guard: + /// the caller acts only on `Ok(true)`, so a re-POSTed signed declaration is refused. The caller + /// MUST have passed [`check_intent_freshness`] first (this stores `declared_at` and COMPACTS the + /// map against the freshness window on every call, so it stays bounded — G-M7 — but it does NOT + /// itself reject a stale intent; that is the dispatcher's fail-closed gate). Durable-before- + /// visible: on a persistence failure the id is rolled back and the error surfaces, and the + /// caller must REFUSE the act (G-M5). A poisoned lock recovers via `into_inner()`. + pub fn record_fresh_intent( + &self, + intent_id: &str, + declared_at_secs: u64, + now_secs: u64, + ) -> std::io::Result { + let grants = match self.grants.write() { + Ok(g) => g, + Err(poisoned) => poisoned.into_inner(), + }; + let mut seen = match self.seen_intents.write() { + Ok(s) => s, + Err(poisoned) => poisoned.into_inner(), + }; + use std::sync::atomic::Ordering::SeqCst; + // Already seen ⇒ replay refused, BEFORE any compaction (never forget an id we are about to + // reject on). + if seen.contains_key(intent_id) { + return Ok(false); + } + // Anti-readmit watermark (red-team, Sprint 19): an id whose declared_at is at/below the + // highest already-EVICTED declared_at was, or is shadowed by, a forgotten dispatch — refuse + // it as a replay. This holds regardless of clock direction, closing the backward-clock-step + // readmission the freshness window alone cannot (freshness ages against a movable clock; + // this watermark never regresses). + let prev_watermark = self.max_evicted_declared_at.load(SeqCst); + if declared_at_secs <= prev_watermark { + return Ok(false); + } + // Compact: drop ids whose declared_at has aged past the whole acceptance window — a re-POST + // of one would be rejected by check_intent_freshness (monotonic clock) AND by the watermark + // (any clock), so forgetting opens no replay. This bounds the map to ~one window of intents + // (no longer monotonic). Compaction runs only here (the write path), so an idle store is not + // pruned — strictly SAFER (idle ⇒ remembered longer); boundedness holds under any traffic + // that reaches the cap. Every eviction raises the watermark to the evicted declared_at. + let cutoff = now_secs.saturating_sub(SEEN_INTENT_RETENTION_SECS); + let mut new_watermark = prev_watermark; + seen.retain(|_, declared_at| { + if *declared_at < cutoff { + new_watermark = new_watermark.max(*declared_at); + false + } else { + true + } + }); + if new_watermark > prev_watermark { + self.max_evicted_declared_at.store(new_watermark, SeqCst); + } + seen.insert(intent_id.to_string(), declared_at_secs); + if let Err(e) = self.persist_locked(&grants, &seen) { + // Roll back the INSERT (the just-added id must not survive a failed persist), but KEEP + // the bumped watermark: compaction already forgot the evicted ids from memory, and an + // evicted id can have declared_at ABOVE prev_watermark — restoring the LOWER prev would + // leave it caught by neither the set (forgotten) nor the watermark (too low), reopening + // the backward-clock replay under a persist failure. The watermark is monotonic and + // fail-closed (higher ⇒ rejects MORE); disk still holds the old (lower) watermark + the + // un-evicted entries, so a restart is also safe. (Re-verification of the F1 fix.) + seen.remove(intent_id); + return Err(e); + } + Ok(true) + } + + /// Revoke EVERY standing grant — the envelope side of the mass kill switch, durable-before- + /// visible. Called alongside an epoch advance (`revoke_all`), which kills every backing token + /// but knows nothing of the envelope registry; without this, an epoch-dead mandate would keep + /// rendering (and, once dispatch is wired, dispatching) as LIVE. Returns how many live + /// envelopes this call killed; on a persistence failure every flag is rolled back and the + /// error surfaces (all-or-nothing — a partially-persisted mass kill is worse than a loud + /// failure, because it looks complete). + pub fn revoke_all(&self) -> std::io::Result { + let mut grants = match self.grants.write() { + Ok(g) => g, + Err(poisoned) => poisoned.into_inner(), + }; + let seen = match self.seen_intents.write() { + Ok(s) => s, + Err(poisoned) => poisoned.into_inner(), + }; + let now = SecureTimestamp::now().unix_secs; + let mut killed_ids = Vec::new(); + for env in grants.values_mut() { + if !env.revoked { + env.revoked = true; + env.revoked_at = Some(now); + killed_ids.push(env.grant_id.clone()); + } + } + if killed_ids.is_empty() { + return Ok(0); + } + if let Err(e) = self.persist_locked(&grants, &seen) { + for id in &killed_ids { + if let Some(env) = grants.get_mut(id) { + env.revoked = false; + env.revoked_at = None; + } + } + return Err(e); + } + Ok(killed_ids.len()) + } + /// True iff an ACTIVE (issued, not revoked, not expired) grant exists for `grant_id`. A read-only /// probe for surfaces that want the live count; the dispatch decision itself always goes through /// the gate, never this shortcut. @@ -772,23 +1624,119 @@ impl StandingGrantService { } } + /// Like [`new`](Self::new) but over a PERSISTENT registry (see + /// [`StandingGrantStore::with_persistence`]): mandates and the replay guard survive restart. + /// Fail-closed at boot — corrupt on-disk state is an error, never silently skipped. + pub fn with_persistence( + audit: Arc, + signing_key: SigningKey, + path: impl AsRef, + ) -> std::io::Result { + let signer_pubkey = signing_key.verifying_key().to_bytes(); + Ok(Self { + store: StandingGrantStore::with_persistence(path)?, + audit, + signing_key, + signer_pubkey, + }) + } + /// Issue a standing grant derived from a REAL issued [`CapabilityToken`] (the cryptographic /// root): the token supplies capsule/resource/action/expiry, the caller supplies the authorized /// method set. Returns the `grant_id` (the token's id) to revoke or dispatch against later. + /// With a persistent registry, a mandate that cannot be durably recorded is NOT issued + /// (fail-closed) — the error surfaces instead. pub fn issue_from_token( &self, token: &CapabilityToken, allowed_methods: BTreeSet, - ) -> String { - let envelope = StandingGrantEnvelope::from_token(token, allowed_methods, false); + agent_pubkey: Option, + dispatch_limit: Option, + responsible_entity: Option, + ) -> std::io::Result { + // Enforce the budget invariant HERE, at the service choke point, not only at the HTTP + // boundary (council red-team F3 / guardian F7): 0 would mint a mandate that renders "Live" + // yet denies every act, and an unclamped limit would uncap the fsync-flood bound (F2). Every + // mint surface (API, gateway shell form) funnels through this, so the invariant holds even + // for a future direct caller — fail-closed at the type's home, not by convention. + if let Some(n) = dispatch_limit { + if n == 0 || n > MANDATE_DISPATCH_LIMIT_MAX { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + format!( + "dispatch_limit must be between 1 and {MANDATE_DISPATCH_LIMIT_MAX} acts \ + per window (got {n}); omit it for the default" + ), + )); + } + } + // Service-layer bound on the responsible entity (council S32 F6): the shared syntactic + // bound, re-checked at the choke point so a non-HTTP caller can't smuggle an + // unbounded/hostile blob onto the signed chain. Syntactic only — never authentication. + if let Some(e) = responsible_entity.as_deref() { + if !crate::capability::responsible_entity_syntax_ok(e) { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidInput, + "responsible_entity must be ≤256 chars of DID charset", + )); + } + } + let envelope = StandingGrantEnvelope::from_token( + token, + allowed_methods, + false, + agent_pubkey, + dispatch_limit, + responsible_entity, + ); let grant_id = envelope.grant_id.clone(); - self.store.issue(envelope); - grant_id + self.store.issue(envelope)?; + Ok(grant_id) + } + + /// The standing grant envelope for `grant_id` (revoked or not), if ever issued. Read-only; + /// an operator/dispatch surface uses it to consult liveness the pure gate cannot re-derive. + pub fn get(&self, grant_id: &str) -> Option { + self.store.get(grant_id) + } + + /// Record a dispatch against the mandate's per-mandate RATE budget; `true` iff within budget. + /// See [`StandingGrantStore::record_dispatch_within_budget`]. `false` ⇒ the caller must REFUSE + /// the act (429). Call AFTER freshness, BEFORE the replay guard's durable write. + pub fn record_dispatch_within_budget(&self, grant_id: &str, now_secs: u64) -> bool { + self.store.record_dispatch_within_budget(grant_id, now_secs) + } + + /// The dispatch-rate budget ENFORCED for `grant_id` (own limit or the global default). See + /// [`StandingGrantStore::dispatch_limit_for`] — the shared resolver behind the over-budget + /// message so it can never misstate what the gate enforces. + pub fn dispatch_limit_for(&self, grant_id: &str) -> u32 { + self.store.dispatch_limit_for(grant_id) + } + + /// Whether any dispatch-rate entry exists (test observability). See + /// [`StandingGrantStore::any_dispatch_rate_entries`]. + pub fn any_dispatch_rate_entries(&self) -> bool { + self.store.any_dispatch_rate_entries() + } + + /// Register an intent id as dispatched; `Ok(true)` iff FRESH. The replay guard — see + /// [`StandingGrantStore::record_fresh_intent`]. The caller must have passed + /// [`check_intent_freshness`] first. On `Err` the caller must REFUSE the act. + pub fn record_fresh_intent( + &self, + intent_id: &str, + declared_at_secs: u64, + now_secs: u64, + ) -> std::io::Result { + self.store + .record_fresh_intent(intent_id, declared_at_secs, now_secs) } - /// Revoke a standing grant by id, fail-closed. Returns `true` iff a live grant was revoked by - /// this call (double-revoke / unknown id → `false`). - pub fn revoke(&self, grant_id: &str) -> bool { + /// Revoke a standing grant by id, fail-closed and durable-before-visible. `Ok(true)` iff a + /// live grant was revoked by this call (double-revoke / unknown id → `Ok(false)`); a + /// persistence failure rolls back and surfaces. + pub fn revoke(&self, grant_id: &str) -> std::io::Result { self.store.revoke(grant_id) } @@ -797,6 +1745,19 @@ impl StandingGrantService { self.store.is_active(grant_id) } + /// Every standing grant issued this runtime lifetime (revoked included, flagged), sorted by + /// id — the operator's mandate list. Read-only; see [`StandingGrantStore::list`]. + pub fn list(&self) -> Vec { + self.store.list() + } + + /// Revoke EVERY standing grant (the envelope side of the mass kill switch — pair with the + /// manager's epoch advance). Returns how many live envelopes were killed by this call; + /// all-or-nothing under a persistent registry. + pub fn revoke_all(&self) -> std::io::Result { + self.store.revoke_all() + } + /// Dispatch a self-declared agent act under its standing grant, fail-closed — the full loop /// (declare → verify `intent ⊆ envelope` → act → reconcile). Thin wrapper over /// [`dispatch_standing_act`] with the service's own store/audit/key. @@ -878,6 +1839,11 @@ mod tests { action: "execute".to_string(), expires_at: Some(SecureTimestamp::after_secs(3600)), revoked: false, + agent_pubkey: None, + token_epoch: 0, + dispatch_limit: None, + revoked_at: None, + responsible_entity: None, } } @@ -1052,7 +2018,7 @@ mod tests { Some(SecureTimestamp::after_secs(3600)), ); let methods: BTreeSet = ["send", "draft"].iter().map(|m| m.to_string()).collect(); - let env = StandingGrantEnvelope::from_token(&token, methods, false); + let env = StandingGrantEnvelope::from_token(&token, methods, false, None, None, None); // The token supplies capsule/resource/action/expiry that were actually signed in. assert_eq!(env.capsule, "vm-agent"); @@ -1091,12 +2057,13 @@ mod tests { None, ); let methods: BTreeSet = ["send"].iter().map(|m| m.to_string()).collect(); - let active = StandingGrantEnvelope::from_token(&token, methods.clone(), false); + let active = + StandingGrantEnvelope::from_token(&token, methods.clone(), false, None, None, None); assert_eq!(active.expires_at, None); assert!(active.is_active(), "None expiry never expires"); // The caller's external revocation check is honored, fail-closed. - let revoked = StandingGrantEnvelope::from_token(&token, methods, true); + let revoked = StandingGrantEnvelope::from_token(&token, methods, true, None, None, None); assert!(!revoked.is_active()); let sk = key(); assert_eq!( @@ -1296,21 +2263,82 @@ mod tests { #[test] fn every_denial_reason_has_a_stable_string() { - for (denial, expected) in [ - (EnvelopeDenial::Revoked, "revoked"), - (EnvelopeDenial::Expired, "expired"), - (EnvelopeDenial::WrongCapsule, "wrong_capsule"), - ( - EnvelopeDenial::MethodNotInEnvelope, - "method_not_in_envelope", - ), - (EnvelopeDenial::WrongResource, "wrong_resource"), - (EnvelopeDenial::WrongAction, "wrong_action"), - ] { + // EXHAUSTIVE by construction: the match below fails to compile when a variant is added, + // forcing its stable on-chain string to be pinned here too. + let all = [ + EnvelopeDenial::Revoked, + EnvelopeDenial::Expired, + EnvelopeDenial::WrongCapsule, + EnvelopeDenial::WrongAgent, + EnvelopeDenial::MethodNotInEnvelope, + EnvelopeDenial::WrongResource, + EnvelopeDenial::WrongAction, + EnvelopeDenial::NoGrant, + ]; + for denial in all { + let expected = match denial { + EnvelopeDenial::Revoked => "revoked", + EnvelopeDenial::Expired => "expired", + EnvelopeDenial::WrongCapsule => "wrong_capsule", + EnvelopeDenial::WrongAgent => "wrong_agent", + EnvelopeDenial::MethodNotInEnvelope => "method_not_in_envelope", + EnvelopeDenial::WrongResource => "wrong_resource", + EnvelopeDenial::WrongAction => "wrong_action", + EnvelopeDenial::NoGrant => "no_standing_grant", + }; assert_eq!(denial.as_str(), expected); } } + #[test] + fn the_signature_preimage_timestamp_encoding_is_frozen() { + // `signable_digest` hashes `declared_at`/`reconciled_at` as serde-JSON, so + // `SecureTimestamp`'s JSON shape (field names AND order, from elastos-common) is part of + // every existing signature's preimage: change it and every previously signed intent stops + // verifying. Pin the exact bytes. + let ts = SecureTimestamp { + unix_secs: 1_700_000_000, + monotonic_seq: 42, + }; + assert_eq!( + serde_json::to_string(&ts).unwrap(), + r#"{"unix_secs":1700000000,"monotonic_seq":42}"#, + "SecureTimestamp's JSON encoding is FROZEN into the intent-signature preimage" + ); + } + + /// Sprint 49 (council guardian F2 — the known-answer ratchet SPEC-mandate-v1 §7 cites): the + /// WHOLE intent-signature preimage — the trailing-NUL domain, the nine fields in order, the + /// LITTLE-endian length prefixes, and the timestamp JSON tail — pinned as ONE fixed digest. + /// The timestamp test above pins one segment; this pins everything: any silent reorder, + /// domain edit, or endianness change in `signable_digest` fails here even though signer and + /// verifier share the code (a round-trip can never catch it). + #[test] + fn the_intent_preimage_digest_is_frozen() { + let decl = IntentDeclarationV1 { + schema: INTENT_DECLARATION_SCHEMA_V1.to_string(), + intent_id: "intent-1".into(), + capsule: "vm-agent".into(), + method_id: "runtime.pay".into(), + input_hash: "abc123".into(), + resource: "elastos://pay/vendor".into(), + action: "execute".into(), + standing_grant_id: "tok-1".into(), + declared_at: SecureTimestamp { + unix_secs: 1_700_000_000, + monotonic_seq: 42, + }, + signer: "00".repeat(32), + signature: String::new(), // not part of the preimage + }; + assert_eq!( + hex::encode(decl.signable_digest()), + "a1b257a80a1710177632ac99438df36a21cddb2e91043015a36c36add666cb6d", + "the FROZEN §7 preimage digest — if this changed, every previously signed intent \ + stops verifying: mint a v2 schema, never edit v1" + ); + } + #[test] fn intent_custody_events_emit_onto_the_durable_chain_and_verify() { // The Kent Beck bar: the declaration, the denial (with reason), and the verdict ride @@ -1495,16 +2523,136 @@ mod tests { action: "execute".to_string(), expires_at, revoked: false, + agent_pubkey: None, + token_epoch: 0, + dispatch_limit: None, + revoked_at: None, + responsible_entity: None, + } + } + + /// Retention semantics (Sprint 23, closes G-M7): the prune ages out grants DEAD past the + /// window, keeps the live and the recently-dead, and NEVER prunes a live grant or a + /// revoked-but-untimeable (legacy, `revoked_at: None`) one by time. + #[test] + fn retention_prune_ages_out_dead_grants_but_keeps_live_and_recent() { + let now = 1_000_000_000u64; + let old = now - GRANT_RETENTION_SECS - 1; // just past the window + let recent = now - 10; // well within the window + let mut grants: HashMap = HashMap::new(); + let mut put = |id: &str, f: &dyn Fn(&mut StandingGrantEnvelope)| { + let mut e = envelope_with(id, None); + f(&mut e); + grants.insert(id.to_string(), e); + }; + // live (never expires) — keep. + put("live", &|_| {}); + // live (future expiry) — keep. + put("live-exp", &|e| { + e.expires_at = Some(SecureTimestamp::at(now + 10_000)) + }); + // revoked long ago — prune. + put("rev-old", &|e| { + e.revoked = true; + e.revoked_at = Some(old); + }); + // revoked just now — keep (within retention). + put("rev-recent", &|e| { + e.revoked = true; + e.revoked_at = Some(recent); + }); + // expired long ago (not revoked) — prune (times off `expires_at`). + put("exp-old", &|e| { + e.expires_at = Some(SecureTimestamp::at(old)) + }); + // expired recently — keep. + put("exp-recent", &|e| { + e.expires_at = Some(SecureTimestamp::at(recent)) + }); + // revoked with NO timestamp (legacy) — keep: untimeable, never time-pruned. + put("rev-legacy", &|e| { + e.revoked = true; + e.revoked_at = None; + }); + + let removed = StandingGrantStore::prune_registry_locked(&mut grants, now, ""); + let gone: std::collections::BTreeSet<&str> = + removed.iter().map(|(id, _)| id.as_str()).collect(); + assert_eq!( + gone, + ["exp-old", "rev-old"].into_iter().collect(), + "only grants dead PAST the retention window age out" + ); + for keep in ["live", "live-exp", "rev-recent", "exp-recent", "rev-legacy"] { + assert!(grants.contains_key(keep), "{keep} must be retained"); } } + /// The hard cap (Sprint 23) reclaims DEAD accumulation without touching a live mandate: over + /// the cap, the oldest-dead grants are evicted first; a live grant is never shed to satisfy it. + #[test] + fn retention_hard_cap_evicts_oldest_dead_never_live() { + let now = 2_000_000_000u64; + let mut grants: HashMap = HashMap::new(); + // A handful of LIVE grants that must all survive even past the cap. + for i in 0..8 { + grants.insert( + format!("live-{i}"), + envelope_with(&format!("live-{i}"), None), + ); + } + // Fill well past the cap with RECENTLY-revoked grants (within retention, so only the cap — + // not time-retention — can shed them), each stamped a distinct recent revoke time. + for i in 0..(REGISTRY_HARD_CAP + 500) { + let mut e = envelope_with(&format!("dead-{i:05}"), None); + e.revoked = true; + e.revoked_at = Some(now - 100 + (i as u64 % 50)); // all recent, varied + grants.insert(format!("dead-{i:05}"), e); + } + StandingGrantStore::prune_registry_locked(&mut grants, now, ""); + assert!( + grants.len() <= REGISTRY_HARD_CAP, + "the registry is hard-bounded at {REGISTRY_HARD_CAP}, got {}", + grants.len() + ); + for i in 0..8 { + assert!( + grants.contains_key(&format!("live-{i}")), + "every LIVE mandate survives the cap — never shed to satisfy a bound" + ); + } + } + + /// A live-set larger than the cap is NOT shed (Sprint 23): live mandates are operator-real + /// authority, bounded by real issuance, never evicted to satisfy the cap. + #[test] + fn retention_never_sheds_a_live_set_over_cap() { + let now = 2_000_000_000u64; + let mut grants: HashMap = HashMap::new(); + for i in 0..(REGISTRY_HARD_CAP + 20) { + grants.insert( + format!("live-{i:05}"), + envelope_with(&format!("live-{i:05}"), None), + ); + } + let removed = StandingGrantStore::prune_registry_locked(&mut grants, now, ""); + assert!(removed.is_empty(), "no live grant is ever pruned"); + assert_eq!( + grants.len(), + REGISTRY_HARD_CAP + 20, + "the live set is kept intact over cap" + ); + } + #[test] fn store_issue_then_get_returns_the_envelope() { let store = StandingGrantStore::new(); assert!(store.get("g1").is_none(), "an unissued grant is absent"); assert!(!store.is_active("g1"), "an unissued grant is not active"); - store.issue(envelope_with("g1", Some(SecureTimestamp::after_secs(3600)))); + store + .issue(envelope_with("g1", Some(SecureTimestamp::after_secs(3600)))) + .unwrap(); let got = store.get("g1").expect("issued grant is retrievable"); assert_eq!(got.grant_id, "g1"); assert!(!got.revoked); @@ -1514,19 +2662,22 @@ mod tests { #[test] fn store_revoke_flips_the_flag_keeps_the_record_and_is_idempotent() { let store = StandingGrantStore::new(); - store.issue(envelope_with("g1", None)); // None expiry ⇒ never expires until revoked. + store.issue(envelope_with("g1", None)).unwrap(); // None expiry ⇒ never expires until revoked. assert!(store.is_active("g1")); - assert!(store.revoke("g1"), "revoking a live grant returns true"); + assert!( + store.revoke("g1").unwrap(), + "revoking a live grant returns true" + ); // The record is KEPT, now marked revoked — queryable as revoked for honest denial. let got = store.get("g1").expect("a revoked grant is still queryable"); assert!(got.revoked, "the stored envelope is marked revoked"); assert!(!store.is_active("g1"), "a revoked grant is not active"); // Idempotent: a second revoke (already revoked) returns false — no live grant was revoked. - assert!(!store.revoke("g1"), "double-revoke returns false"); + assert!(!store.revoke("g1").unwrap(), "double-revoke returns false"); // Revoking an unknown id is a fail-closed no-op, never a panic. - assert!(!store.revoke("does-not-exist")); + assert!(!store.revoke("does-not-exist").unwrap()); } #[test] @@ -1536,7 +2687,7 @@ mod tests { // Issuing an already-revoked envelope stores it as revoked — issue never un-revokes. let mut revoked_env = envelope_with("g1", None); revoked_env.revoked = true; - store.issue(revoked_env); + store.issue(revoked_env).unwrap(); assert!( !store.is_active("g1"), "an issued-revoked grant is not active" @@ -1544,7 +2695,9 @@ mod tests { assert!(store.get("g1").unwrap().revoked); // A past expiry deactivates a grant even though it was never revoked (fail-closed on time). - store.issue(envelope_with("g2", Some(SecureTimestamp::after_secs(0)))); + store + .issue(envelope_with("g2", Some(SecureTimestamp::after_secs(0)))) + .unwrap(); assert!( !store.is_active("g2"), "an expired grant is inactive without any revocation" @@ -1558,7 +2711,7 @@ mod tests { /// Issue `an_envelope(methods)` (grant_id "grant-1") into a fresh store. fn store_with(methods: &[&str]) -> StandingGrantStore { let store = StandingGrantStore::new(); - store.issue(an_envelope(methods)); + store.issue(an_envelope(methods)).unwrap(); store } @@ -1660,7 +2813,10 @@ mod tests { let (_dir, log) = gate_log(); let sk = key(); let store = store_with(&["send"]); - assert!(store.revoke("grant-1"), "revoke the standing grant"); + assert!( + store.revoke("grant-1").unwrap(), + "revoke the standing grant" + ); let intent = an_intent(&sk, "send", "args-abc"); let ran = std::cell::Cell::new(false); let outcome = dispatch_standing_act( @@ -1746,8 +2902,11 @@ mod tests { &token, ["send"].iter().map(|m| m.to_string()).collect(), false, + None, + None, + None, ); - store.issue(envelope); + store.issue(envelope).unwrap(); // A fresh, correctly-signed intent for THIS token's grant, invoking an in-envelope method. let declare = |args: &str| { @@ -1789,7 +2948,10 @@ mod tests { // 4. Revoke the standing grant by the TOKEN's id — the SAME dispatch is now denied, // fail-closed, and the act never runs. This is the kill switch on an autonomous agent. - assert!(store.revoke(&grant_id), "revoke the token's standing grant"); + assert!( + store.revoke(&grant_id).unwrap(), + "revoke the token's standing grant" + ); let ran = std::cell::Cell::new(false); let after = dispatch_standing_act( &store, @@ -1856,8 +3018,15 @@ mod tests { SecureTimestamp::now(), Some(SecureTimestamp::after_secs(3600)), ); - let grant_id = - svc.issue_from_token(&token, ["send"].iter().map(|m| m.to_string()).collect()); + let grant_id = svc + .issue_from_token( + &token, + ["send"].iter().map(|m| m.to_string()).collect(), + None, + None, + None, + ) + .unwrap(); assert_eq!(grant_id, token.id().to_string()); assert!(svc.is_active(&grant_id), "a freshly issued grant is active"); @@ -1891,7 +3060,7 @@ mod tests { ); // Revoke through the service: the grant goes inactive and the next dispatch is denied. - assert!(svc.revoke(&grant_id)); + assert!(svc.revoke(&grant_id).unwrap()); assert!(!svc.is_active(&grant_id)); let ran = std::cell::Cell::new(false); let after = svc.dispatch(&declare("a2"), || { @@ -1912,6 +3081,62 @@ mod tests { assert_eq!(summary.denied, 1); } + /// The dispatch-budget invariant lives at the SERVICE layer, not only the HTTP boundary + /// (council red-team F3 / guardian F7): `issue_from_token` itself refuses a 0 budget (would + /// mint a Live-looking mandate that denies every act) and one over `MANDATE_DISPATCH_LIMIT_MAX` + /// (would uncap the fsync-flood bound — red-team F2), while a value inside [1, MAX] and `None` + /// mint fine. So even a future non-HTTP caller cannot store an out-of-range budget. + #[test] + fn issue_from_token_rejects_out_of_range_dispatch_limit() { + use crate::capability::token::{Action, CapabilityToken, ResourceId}; + let dir = tempfile::tempdir().unwrap(); + let audit = std::sync::Arc::new( + crate::primitives::audit::AuditLog::with_file(dir.path().join("a.log")).unwrap(), + ); + let sk = key(); + let svc = StandingGrantService::new(audit, sk); + let mk_token = || { + CapabilityToken::new( + "vm-agent".to_string(), + [0u8; 32], + ResourceId::new("elastos://mail/send"), + Action::Execute, + Default::default(), + SecureTimestamp::now(), + Some(SecureTimestamp::after_secs(3600)), + ) + }; + let methods = || { + ["send"] + .iter() + .map(|m| m.to_string()) + .collect::>() + }; + // Zero and over-max are refused with InvalidInput — fail-closed, not stored. + for bad in [Some(0u32), Some(MANDATE_DISPATCH_LIMIT_MAX + 1)] { + let err = svc + .issue_from_token(&mk_token(), methods(), None, bad, None) + .expect_err("out-of-range dispatch_limit is refused at the service layer"); + assert_eq!(err.kind(), std::io::ErrorKind::InvalidInput); + } + // The boundary value MAX and a normal dial and None all mint fine. + assert!(svc + .issue_from_token( + &mk_token(), + methods(), + None, + Some(MANDATE_DISPATCH_LIMIT_MAX), + None + ) + .is_ok()); + assert!(svc + .issue_from_token(&mk_token(), methods(), None, Some(5), None) + .is_ok()); + assert!(svc + .issue_from_token(&mk_token(), methods(), None, None, None) + .is_ok()); + } + #[test] fn service_dispatch_with_no_issued_grant_is_denied_no_grant() { let dir = tempfile::tempdir().unwrap(); @@ -1988,7 +3213,7 @@ mod tests { ); // Issue a grant, then preview both an in-envelope and an out-of-envelope intent. - svc.store.issue(an_envelope(&["send"])); + svc.store.issue(an_envelope(&["send"])).unwrap(); assert_eq!(svc.preview(&intent), EnvelopeCheck::Allowed); let out = an_intent(&sk, "delete", "h1"); // method not in the envelope assert!(matches!( @@ -2007,7 +3232,7 @@ mod tests { ); let sk = key(); let svc = StandingGrantService::new(audit, sk.clone()); - svc.store.issue(an_envelope(&["send"])); + svc.store.issue(an_envelope(&["send"])).unwrap(); // Authentic intent ⇒ Some(verdict). let intent = an_intent(&sk, "send", "h1"); @@ -2022,4 +3247,557 @@ mod tests { forged.action = "admin".to_string(); assert_eq!(svc.authenticated_preview(&forged), None); } + + // ── Durable mandates (G-M5): the registry + replay guard survive restart ── + + /// The core reboot invariant, all four legs on ONE store file: after a reopen, a LIVE mandate + /// stays live, a REVOKED mandate stays dead (never crash-revived), an EXPIRED mandate reads + /// inactive, and a dispatched intent id is STILL refused (the replay guard survives — G-M5). + #[test] + fn persistent_store_survives_reopen_live_dead_and_replay() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("standing_grants.json"); + { + let store = StandingGrantStore::with_persistence(&path).unwrap(); + store + .issue(envelope_with( + "live-1", + Some(SecureTimestamp::after_secs(3600)), + )) + .unwrap(); + store.issue(envelope_with("dead-1", None)).unwrap(); + assert!(store.revoke("dead-1").unwrap()); + store + .issue(envelope_with("exp-1", Some(SecureTimestamp::after_secs(0)))) + .unwrap(); + let now = SecureTimestamp::now().unix_secs; + assert!(store.record_fresh_intent("intent-once", now, now).unwrap()); + } // drop = the "restart" + let store = StandingGrantStore::with_persistence(&path).unwrap(); + assert!( + store.is_active("live-1"), + "a live mandate survives reboot LIVE" + ); + assert!( + !store.is_active("dead-1"), + "a revoked mandate stays DEAD after reboot — never crash-revived" + ); + assert!( + store.get("dead-1").expect("still queryable").revoked, + "the revoked record is retained as revoked, not vanished" + ); + assert!( + !store.is_active("exp-1"), + "an expired mandate reloads inactive" + ); + let now = SecureTimestamp::now().unix_secs; + assert!( + !store.record_fresh_intent("intent-once", now, now).unwrap(), + "the replay guard survives reboot: the same intent id is refused (G-M5)" + ); + assert!( + store.record_fresh_intent("intent-new", now, now).unwrap(), + "fresh intents still register after reload" + ); + assert_eq!( + store.list().len(), + 3, + "every issued mandate is still listed" + ); + } + + /// The per-mandate RATE budget (G-M7): a mandate may perform up to the limit per window, then + /// is refused; a NEW window resets it; and the budget is PER grant_id (one mandate's flood does + /// not spend another's). + #[test] + fn dispatch_rate_budget_bounds_a_mandate_then_resets_next_window() { + let store = StandingGrantStore::new(); + let t0 = 1_000_000u64; + // Up to the limit is allowed within the window... + for i in 0..MANDATE_DISPATCH_LIMIT { + assert!( + store.record_dispatch_within_budget("g1", t0), + "act {i} within budget" + ); + } + // ...the next act in the same window is refused. + assert!( + !store.record_dispatch_within_budget("g1", t0), + "over budget in the same window" + ); + // A DIFFERENT mandate has its own budget — not spent by g1's flood. + assert!( + store.record_dispatch_within_budget("g2", t0), + "g2 has its own budget" + ); + // A new window (past the window end) resets g1. + let t1 = t0 + MANDATE_DISPATCH_WINDOW_SECS; + assert!( + store.record_dispatch_within_budget("g1", t1), + "the budget resets in the next window" + ); + } + + /// The rate map is BOUNDED even against a SAME-WINDOW flood of distinct grant_ids (the attack + /// the council flagged: the across-window prune reclaims nothing inside one window, so a hard + /// cap must refuse new keys at capacity). This is the ratchet reproducing that exact failure — + /// every id shares one window `t0`, so nothing is ever stale, yet the map must stay bounded. + #[test] + fn dispatch_rate_map_is_bounded_against_distinct_grant_spam() { + let store = StandingGrantStore::new(); + let t0 = 1_000u64; + // Flood distinct grant_ids ALL WITHIN ONE WINDOW — none ever goes stale during the flood, + // so the across-window prune cannot help; only the hard cap can bound this. + for i in 0..(DISPATCH_RATE_SOFT_CAP * 4) { + store.record_dispatch_within_budget(&format!("flood-{i}"), t0); + } + let n = store + .dispatch_rate + .read() + .map(|m| m.len()) + .unwrap_or(usize::MAX); + assert!( + n <= DISPATCH_RATE_SOFT_CAP + 1, + "same-window distinct-grant_id flood is hard-capped at ~{DISPATCH_RATE_SOFT_CAP}, got {n}" + ); + // The hard cap must NOT deny an ALREADY-SEEN grant_id (a real mandate keeps acting): a key + // that already has an entry is still counted even while the map is at capacity. + assert!( + store.record_dispatch_within_budget("flood-0", t0), + "an existing grant_id is still counted at capacity — a real mandate is never shed" + ); + // A brand-new key at capacity IS refused (fail-closed memory bound). + assert!( + !store.record_dispatch_within_budget("brand-new-at-capacity", t0), + "a new grant_id is refused while the map is at its hard cap" + ); + } + + /// Rate is a FIRST-CLASS grant property (Sprint 22): a mandate issued with its own + /// `dispatch_limit` is enforced at THAT budget — resolved from the registry by the store + /// itself, so no caller can pass a wrong limit — while a mandate without one gets the global + /// default, and the custom budget still resets on a new window. + #[test] + fn per_mandate_dispatch_limit_overrides_the_default() { + let store = StandingGrantStore::new(); + let mut tight = envelope_with("g-tight", None); + tight.dispatch_limit = Some(3); + store.issue(tight).unwrap(); + store.issue(envelope_with("g-default", None)).unwrap(); + let t0 = 1_000_000u64; + for i in 0..3 { + assert!( + store.record_dispatch_within_budget("g-tight", t0), + "act {i} within its own budget" + ); + } + assert!( + !store.record_dispatch_within_budget("g-tight", t0), + "the mandate's OWN limit (3) binds, not the global default" + ); + // The default-budget mandate is unaffected by the tight one's ceiling. + for i in 0..4 { + assert!( + store.record_dispatch_within_budget("g-default", t0), + "default act {i}" + ); + } + // The custom budget resets on a new window like the default does. + let t1 = t0 + MANDATE_DISPATCH_WINDOW_SECS; + assert!( + store.record_dispatch_within_budget("g-tight", t1), + "the custom budget refills next window" + ); + // A tampered zero-rate entry (the mint refuses Some(0)) denies EVERY act, fail-closed — + // never "one per window" via the reset branch. + let mut zeroed = envelope_with("g-zero", None); + zeroed.dispatch_limit = Some(0); + store.issue(zeroed).unwrap(); + assert!( + !store.record_dispatch_within_budget("g-zero", t0), + "a zero limit denies every act (tamper fail-closed)" + ); + } + + /// Snapshot compatibility (Sprint 22): a v2 file (envelopes predate `dispatch_limit`) MIGRATES + /// on load — every mandate gets `None` (the global default, exactly the budget it was enforced + /// under when written) — and a v3 rewrite round-trips a custom limit durably. A v3 file with + /// the `dispatch_limit` KEY dropped refuses to load (widen-proof: a same-disk edit must not + /// silently reset an operator-tightened budget to the default). + #[test] + fn v2_snapshot_migrates_dispatch_limit_and_v3_roundtrips_it() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("standing_grants.json"); + // A hand-written v2 file: one mandate, no dispatch_limit key anywhere (pre-Sprint-22). + std::fs::write( + &path, + r#"{"version":2,"grants":[{"grant_id":"g1","capsule":"vm-agent", + "allowed_methods":["send"],"resource":"elastos://mail/send","action":"execute", + "expires_at":null,"agent_pubkey":null,"revoked":false,"token_epoch":0}], + "seen_intents":[{"id":"seen-1","declared_at":100}],"max_evicted_declared_at":7}"#, + ) + .unwrap(); + let store = StandingGrantStore::with_persistence(&path).unwrap(); + let g1 = store.get("g1").expect("the v2 mandate survives migration"); + assert_eq!( + g1.dispatch_limit, None, + "migrated mandates run at the global default" + ); + // Issue a custom-rate mandate; the store now writes v3 — reload must preserve the dial. + let mut dialed = envelope_with("g-dialed", None); + dialed.dispatch_limit = Some(5); + store.issue(dialed).unwrap(); + let reopened = StandingGrantStore::with_persistence(&path).unwrap(); + assert_eq!( + reopened.get("g-dialed").unwrap().dispatch_limit, + Some(5), + "a custom budget survives restart (v3 round-trip)" + ); + assert_eq!(reopened.get("g1").unwrap().dispatch_limit, None); + // Widen-proof: a v3 file whose envelope DROPS the dispatch_limit key refuses to load. + std::fs::write( + &path, + r#"{"version":3,"grants":[{"grant_id":"g1","capsule":"vm-agent", + "allowed_methods":["send"],"resource":"elastos://mail/send","action":"execute", + "expires_at":null,"agent_pubkey":null,"revoked":false,"token_epoch":0}], + "seen_intents":[],"max_evicted_declared_at":0}"#, + ) + .unwrap(); + assert!( + StandingGrantStore::with_persistence(&path).is_err(), + "a v3 envelope missing the dispatch_limit KEY is corrupt, never 'default rate'" + ); + } + + /// Retention end-to-end (Sprint 23): `revoke` stamps `revoked_at` and it round-trips restart; + /// a pre-Sprint-23 v3 file with NO `revoked_at` key loads as `None` (serde-default, no version + /// bump / migration needed); and `issue` PRUNES a grant expired past the retention window. + #[test] + fn revoke_stamps_revoked_at_roundtrips_and_issue_prunes_expired() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("standing_grants.json"); + // A v3 file predating Sprint 23: envelope carries dispatch_limit but NO revoked_at key. + std::fs::write( + &path, + r#"{"version":3,"grants":[{"grant_id":"g-live","capsule":"vm-agent", + "allowed_methods":["send"],"resource":"elastos://mail/send","action":"execute", + "expires_at":null,"agent_pubkey":null,"revoked":false,"token_epoch":0, + "dispatch_limit":null}], + "seen_intents":[],"max_evicted_declared_at":0}"#, + ) + .unwrap(); + let store = StandingGrantStore::with_persistence(&path).unwrap(); + let live = store + .get("g-live") + .expect("a pre-Sprint-23 v3 file loads (revoked_at defaults)"); + assert_eq!( + live.revoked_at, None, + "a missing revoked_at defaults to None — no migration" + ); + + // Revoke stamps a time; it survives restart. + assert!(store.revoke("g-live").unwrap()); + let reopened = StandingGrantStore::with_persistence(&path).unwrap(); + let revd = reopened.get("g-live").expect("still present, revoked"); + assert!(revd.revoked, "the revoke round-trips"); + assert!( + revd.revoked_at.is_some(), + "and the revoke TIME round-trips (Sprint 23)" + ); + + // A grant expired PAST the retention window is pruned the next time the registry grows. + let realnow = SecureTimestamp::now().unix_secs; + let mut ancient = envelope_with("g-ancient", None); + ancient.expires_at = Some(SecureTimestamp::at(realnow - GRANT_RETENTION_SECS - 100)); + reopened.issue(ancient).unwrap(); // exempt on its own issue — still present here + assert!( + reopened.get("g-ancient").is_some(), + "the just-issued grant is exempt from its own prune" + ); + // Issuing ANOTHER grant runs the prune with the ancient one no longer exempt → it ages out. + reopened.issue(envelope_with("g-new", None)).unwrap(); + assert!( + reopened.get("g-ancient").is_none(), + "a grant dead past the retention window is pruned when the registry next grows" + ); + assert!(reopened.get("g-new").is_some(), "the fresh grant is kept"); + assert!( + reopened.get("g-live").is_some(), + "the recently-revoked grant is still within retention" + ); + } + + /// The freshness window (G-M7): a declaration expires (too old) and a future-dated one is + /// refused; a just-declared one passes. Pure over unix seconds. + #[test] + fn freshness_window_rejects_stale_and_future_dated() { + let now = 1_000_000u64; + assert!( + check_intent_freshness(now, now).is_ok(), + "declared now → fresh" + ); + assert!( + check_intent_freshness(now - MAX_INTENT_AGE_SECS, now).is_ok(), + "at the age edge → fresh" + ); + assert_eq!( + check_intent_freshness(now - MAX_INTENT_AGE_SECS - 1, now), + Err(FreshnessError::Stale), + "one second past the age → stale" + ); + assert!( + check_intent_freshness(now + MAX_CLOCK_SKEW_SECS, now).is_ok(), + "at the skew edge → fresh" + ); + assert_eq!( + check_intent_freshness(now + MAX_CLOCK_SKEW_SECS + 1, now), + Err(FreshnessError::FutureDated), + "one second past the skew → future-dated" + ); + } + + /// The replay guard is BOUNDED, not monotonic (G-M7): recording a fresh intent COMPACTS ids + /// whose declared_at has aged past the window — but a replay of a STILL-remembered id is caught + /// BEFORE compaction, so bounding never opens a replay. + #[test] + fn seen_set_compacts_aged_ids_but_still_catches_in_window_replay() { + let store = StandingGrantStore::new(); // memory-only is enough for the guard logic + let base = 10_000_000u64; + // An OLD intent recorded when "now" was `base`. + assert!(store.record_fresh_intent("old", base, base).unwrap()); + // Much later, a fresh intent — its recording compacts "old" (aged past retention). + let later = base + SEEN_INTENT_RETENTION_SECS + 10; + assert!(store.record_fresh_intent("recent", later, later).unwrap()); + // "old" was forgotten (bounded), so re-recording it as if fresh-at-`later` succeeds — but in + // production `check_intent_freshness` would reject a re-POST carrying old's real declared_at. + assert!( + store.record_fresh_intent("old", later, later).unwrap(), + "an aged id is compacted out — the freshness gate is what stops its replay" + ); + // A replay of a STILL-in-window id is refused (caught before compaction). + assert!( + !store.record_fresh_intent("recent", later, later).unwrap(), + "an in-window id is still remembered → replay refused" + ); + } + + /// The BACKWARD-CLOCK replay hole (red-team, Sprint 19) is CLOSED by the anti-readmit + /// watermark: an intent evicted while the clock was high cannot be replayed after the clock + /// rewinds into its freshness window. Reproduces the exact attack sequence. + #[test] + fn backward_clock_step_cannot_readmit_an_evicted_intent() { + let store = StandingGrantStore::new(); + let d = 10_000_000u64; // captured intent X's declared_at + // 1. X dispatched legitimately at wall-time ≈ d — remembered. + assert!(store.record_fresh_intent("X", d, d).unwrap()); + // 2. Clock advances past d + retention; another dispatch compacts X out (and raises the + // watermark to ≥ d). + let high = d + SEEN_INTENT_RETENTION_SECS + 100; + assert!(store.record_fresh_intent("Y", high, high).unwrap()); + // 3. Clock steps BACKWARD to ≈ d (t2 within X's freshness window). Freshness would ACCEPT + // X here (that is the regression) — but the watermark refuses the readmit. + let t2 = d; // check_intent_freshness(d, t2) == Ok — the dangerous case + assert_eq!( + check_intent_freshness(d, t2), + Ok(()), + "freshness alone would accept the replay" + ); + assert!( + !store.record_fresh_intent("X", d, t2).unwrap(), + "the watermark refuses X's replay regardless of the clock rewind — no double-act" + ); + // A genuinely NEW, newer intent still acts (the watermark only blocks at/below evicted). + assert!(store.record_fresh_intent("Z", high + 1, high + 1).unwrap()); + } + + /// The watermark survives restart (it is persisted), so the backward-clock hole stays closed + /// across a reboot too. + #[test] + fn evicted_watermark_persists_across_restart() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("standing_grants.json"); + let d = 20_000_000u64; + { + let store = StandingGrantStore::with_persistence(&path).unwrap(); + store.record_fresh_intent("X", d, d).unwrap(); + let high = d + SEEN_INTENT_RETENTION_SECS + 100; + store.record_fresh_intent("Y", high, high).unwrap(); // evicts X, persists watermark + } // restart + let store = StandingGrantStore::with_persistence(&path).unwrap(); + assert!( + !store.record_fresh_intent("X", d, d).unwrap(), + "the persisted watermark still refuses X after a reboot" + ); + } + + /// Even when the compacting write FAILS to persist, the bumped watermark is KEPT (not rolled + /// back to the lower prev) — so an id evicted from memory during that failed call still cannot + /// be replayed (re-verification of the F1 fix: restoring the low watermark would have reopened + /// the hole under a persist failure). The evicted id is caught by the retained watermark before + /// any persist is attempted. + #[test] + fn persist_failure_keeps_the_watermark_so_an_evicted_id_cannot_replay() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("standing_grants.json"); + let d = 30_000_000u64; + let store = StandingGrantStore::with_persistence(&path).unwrap(); + store.record_fresh_intent("X", d, d).unwrap(); + // Squat the temp path so the NEXT (compacting) persist fails. + std::fs::create_dir(path.with_extension("tmp")).unwrap(); + let high = d + SEEN_INTENT_RETENTION_SECS + 100; + assert!( + store.record_fresh_intent("Y", high, high).is_err(), + "the compacting write fails to persist" + ); + // X was evicted in that failed call; a replay of X is refused by the RETAINED watermark + // (the check runs before any persist, so it succeeds even while the dir is squatted). + assert!( + !store.record_fresh_intent("X", d, d).unwrap(), + "the retained watermark still refuses the evicted id after a persist failure" + ); + } + + /// A v1 snapshot (bare-string seen ids, no timestamps) MIGRATES on load — mandates AND the + /// replay guard are preserved (never a fail-closed refusal that would drop them on upgrade). + #[test] + fn v1_snapshot_migrates_preserving_mandates_and_replay_guard() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("standing_grants.json"); + // A hand-written v1 file: one mandate + one seen intent, old bare-string format. + std::fs::write( + &path, + r#"{"version":1,"grants":[{"grant_id":"g1","capsule":"vm-agent", + "allowed_methods":["send"],"resource":"elastos://mail/send","action":"execute", + "expires_at":null,"agent_pubkey":null,"revoked":false,"token_epoch":0}], + "seen_intents":["legacy-intent"]}"#, + ) + .unwrap(); + let store = StandingGrantStore::with_persistence(&path).unwrap(); + assert!(store.is_active("g1"), "the v1 mandate survives migration"); + let now = SecureTimestamp::now().unix_secs; + assert!( + !store + .record_fresh_intent("legacy-intent", now, now) + .unwrap(), + "the migrated replay guard still refuses the legacy intent id" + ); + // And it is now written back as v2 (a fresh intent persists in the new format). + assert!(store.record_fresh_intent("new-intent", now, now).unwrap()); + let reopened = StandingGrantStore::with_persistence(&path).unwrap(); + assert!( + !reopened + .record_fresh_intent("new-intent", now, now) + .unwrap(), + "the v2 rewrite round-trips the guard" + ); + } + + /// Fail-closed boot: a present-but-corrupt registry file is a loud error, never silently + /// skipped (a skipped record could resurrect a revoked mandate or reopen a replay window). + #[test] + fn persistent_store_refuses_corrupt_state_at_boot() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("standing_grants.json"); + std::fs::write(&path, "{not json").unwrap(); + let err = StandingGrantStore::with_persistence(&path) + .err() + .expect("corrupt mandate state must refuse to boot"); + assert_eq!(err.kind(), std::io::ErrorKind::InvalidData); + + // Same for a future/unknown snapshot version — never guess at semantics. + std::fs::write(&path, r#"{"version":99,"grants":[],"seen_intents":[]}"#).unwrap(); + let err = StandingGrantStore::with_persistence(&path) + .err() + .expect("unknown version must refuse to boot"); + assert_eq!(err.kind(), std::io::ErrorKind::InvalidData); + } + + /// Widen-proof reload (guardian F3): a snapshot edit that DROPS a narrowing `Option` key must + /// refuse to load, never silently widen — a missing `agent_pubkey` would UNBIND an agent-bound + /// mandate, a missing `expires_at` would immortalize it. An explicit `null` (what the runtime + /// itself writes for None) still loads. Unknown fields also refuse (version-rollback safety). + #[test] + fn reload_refuses_dropped_option_keys_and_unknown_fields() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("standing_grants.json"); + let base = |fields: &str| { + format!( + r#"{{"version":1,"grants":[{{"grant_id":"g1","capsule":"vm-agent", + "allowed_methods":["send"],"resource":"elastos://mail/send", + "action":"execute",{fields}"revoked":false,"token_epoch":0}}], + "seen_intents":[]}}"# + ) + }; + // Both keys present (explicit null) — loads, honestly None. + std::fs::write(&path, base(r#""expires_at":null,"agent_pubkey":null,"#)).unwrap(); + let store = StandingGrantStore::with_persistence(&path).unwrap(); + assert!(store.is_active("g1")); + + // agent_pubkey KEY dropped — refuses (would unbind an agent-bound mandate). + std::fs::write(&path, base(r#""expires_at":null,"#)).unwrap(); + assert!(StandingGrantStore::with_persistence(&path).is_err()); + + // expires_at KEY dropped — refuses (would immortalize the mandate). + std::fs::write(&path, base(r#""agent_pubkey":null,"#)).unwrap(); + assert!(StandingGrantStore::with_persistence(&path).is_err()); + + // An unknown field — refuses (a binary rollback must not silently drop semantics). + std::fs::write( + &path, + base(r#""expires_at":null,"agent_pubkey":null,"future_narrowing_field":true,"#), + ) + .unwrap(); + assert!(StandingGrantStore::with_persistence(&path).is_err()); + } + + /// Durable-before-visible: when the snapshot write FAILS, the mutation rolls back and the + /// error surfaces — memory never runs ahead of disk. (Seam: a DIRECTORY squatting on the + /// snapshot's temp path makes `File::create` fail — works even when the test runs as root, + /// which ignores permission bits.) + #[test] + fn persist_failure_rolls_back_and_surfaces() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("standing_grants.json"); + let store = StandingGrantStore::with_persistence(&path).unwrap(); + store.issue(envelope_with("g1", None)).unwrap(); + + // Squat a directory on the temp path so the NEXT snapshot write fails. + let tmp_path = path.with_extension("tmp"); + std::fs::create_dir(&tmp_path).unwrap(); + + assert!( + store.issue(envelope_with("g2", None)).is_err(), + "issue surfaces the failure" + ); + assert!( + store.get("g2").is_none(), + "the unpersistable mandate was NOT issued" + ); + assert!(store.revoke("g1").is_err(), "revoke surfaces the failure"); + assert!( + store.is_active("g1"), + "the unpersistable revoke did not half-apply" + ); + let now = SecureTimestamp::now().unix_secs; + assert!( + store.record_fresh_intent("i1", now, now).is_err(), + "replay-guard write surfaces" + ); + // Clear the failure and verify the store still works (loud failure, re-runnable). + std::fs::remove_dir(&tmp_path).unwrap(); + assert!( + store.revoke("g1").unwrap(), + "after the failure clears, the revoke lands" + ); + assert!( + store + .record_fresh_intent( + "i1", + SecureTimestamp::now().unix_secs, + SecureTimestamp::now().unix_secs + ) + .unwrap(), + "the rolled-back intent id was not half-registered" + ); + } } diff --git a/elastos/crates/elastos-runtime/src/capability/manager.rs b/elastos/crates/elastos-runtime/src/capability/manager.rs index 9cfbb312..6db27f0f 100644 --- a/elastos/crates/elastos-runtime/src/capability/manager.rs +++ b/elastos/crates/elastos-runtime/src/capability/manager.rs @@ -282,23 +282,40 @@ impl CapabilityManager { ) } - /// Grant a new capability token - pub fn grant( + /// Like [`standing_grant_service`](Self::standing_grant_service) but PERSISTENT: the mandate + /// registry and its replay guard are snapshot-backed at `path` and survive restart (G-M5). + /// Fail-closed at boot — corrupt on-disk mandate state is an error, never silently skipped. + /// Construct ONCE and share; two services over the same path would clobber each other's + /// snapshots. + pub fn standing_grant_service_with_persistence( + &self, + path: impl AsRef, + ) -> std::io::Result { + crate::capability::intent::StandingGrantService::with_persistence( + self.audit_log.clone(), + self.signing_key.clone(), + path, + ) + } + + /// Build + sign a capability token (the shared mint core for [`grant`](Self::grant) and + /// [`grant_durable`](Self::grant_durable)). Records the request metric. Does NOT audit — the + /// caller chooses the audit discipline (best-effort vs fail-closed), so the two mint surfaces + /// can never drift on how a token is minted, only on how its grant event is recorded. + fn mint_signed_token( &self, capsule_id: &str, - resource: ResourceId, + resource: &ResourceId, action: Action, constraints: TokenConstraints, expiry: Option, ) -> CapabilityToken { let issued_at = SecureTimestamp::now(); - - // Ensure token epoch is at least current epoch + // Ensure token epoch is at least current epoch. let mut constraints = constraints; if constraints.epoch < self.store.current_epoch() { constraints.epoch = self.store.current_epoch(); } - let mut token = CapabilityToken::new( capsule_id.to_string(), self.public_key_bytes(), @@ -308,20 +325,75 @@ impl CapabilityManager { issued_at, expiry, ); - - // Sign the token token.sign(&self.signing_key); - - // Record metrics self.metrics.record_capability_request(capsule_id); + token + } - // Audit log + /// Grant a new capability token. The grant event is audited BEST-EFFORT (a lost audit append + /// does not fail the grant) — the ephemeral hot path for tokens that are not the durable, + /// provable mandate primitive. For a mandate (whose portable receipt IS its record, and whose + /// registry entry is now retention-pruned — Sprint 23), use [`grant_durable`](Self::grant_durable) + /// so the grant event is guaranteed on the chain before the mandate exists. + pub fn grant( + &self, + capsule_id: &str, + resource: ResourceId, + action: Action, + constraints: TokenConstraints, + expiry: Option, + ) -> CapabilityToken { + let token = self.mint_signed_token(capsule_id, &resource, action, constraints, expiry); + // Audit log (best-effort). self.audit_log .capability_grant(&token.id, capsule_id, &resource, action, expiry); - token } + /// Grant a capability token FAIL-CLOSED: emit the signed durable `CapabilityGrant` record + /// BEFORE returning the token (emit-before-issue, mirroring [`revoke`](Self::revoke)'s + /// emit-before-mutate). If the audit write fails the grant ABORTS — the token is never returned, + /// so the caller never issues a mandate whose grant event is not on the chain. This is the mint + /// side of "the chain is the permanent record": a durable, retention-pruned mandate + /// (Sprint 23/24) can never exist without a provable grant event, closing the Sprint 23 council + /// F1 corner (a best-effort mint whose audit was lost, once pruned, had no trace). Accepted + /// tradeoff, symmetric with revoke: a mandate that cannot be recorded does not happen. + pub fn grant_durable( + &self, + capsule_id: &str, + resource: ResourceId, + action: Action, + constraints: TokenConstraints, + expiry: Option, + responsible_entity: Option, + ) -> Result { + // Service-layer bound (council S32 F6): the responsible entity is written VERBATIM into the + // signed chain here, so the shared syntactic bound is re-applied at this choke point — a + // non-HTTP caller cannot smuggle an unbounded/hostile blob onto the chain. + if let Some(e) = responsible_entity.as_deref() { + if !crate::capability::responsible_entity_syntax_ok(e) { + return Err(AuditError::Serialize( + "responsible_entity must be ≤256 chars of DID charset".to_string(), + )); + } + } + let token = self.mint_signed_token(capsule_id, &resource, action, constraints, expiry); + // Emit-before-issue: the durable signed grant record must land before the token is handed + // back. On failure the token is dropped here — never issued, never stored in any registry. + self.audit_log.emit(AuditEvent::CapabilityGrant { + timestamp: SecureTimestamp::now(), + token_id: token.id.to_string(), + capsule_id: capsule_id.to_string(), + resource: resource.to_string(), + action: action.to_string(), + expiry, + // Sprint 32: the liability binding rides the SIGNED grant record — who is accountable + // for every act under this mandate, provable in the exported receipt. + responsible_entity, + })?; + Ok(token) + } + /// Refund one consumed use of a token (saturating). The caller must only /// invoke this when the consumed use was provably a NO-OP — e.g. the act it /// authorized never reached a provider (a routing failure), so no side effect @@ -471,6 +543,7 @@ impl CapabilityManager { resource: requested_resource.to_string(), action: requested_action.to_string(), success: true, + rail_ref: None, }) .map_err(|_| ValidationError::AuditWriteFailed)?; } else { @@ -664,6 +737,20 @@ impl CapabilityManager { self.store.current_epoch() } + /// Read-only probe: has this token id been individually revoked? For operator surfaces that + /// must not render a killed mandate as live. The enforcement decision itself always goes + /// through [`validate`](Self::validate), never this shortcut. + pub async fn is_token_revoked(&self, token_id: &TokenId) -> bool { + self.store.is_token_revoked(token_id).await + } + + /// Read-only probe: is a token minted at `token_epoch` still epoch-valid (not invalidated by a + /// later `revoke_all`/key-rotation epoch advance)? For dispatch liveness the pure envelope gate + /// cannot re-derive. Enforcement still goes through [`validate`](Self::validate). + pub fn is_epoch_valid(&self, token_epoch: u64) -> bool { + self.store.is_epoch_valid(token_epoch) + } + /// Get reference to the audit log pub fn audit_log(&self) -> &Arc { &self.audit_log @@ -872,6 +959,54 @@ mod tests { let _ = std::fs::remove_file(&path); } + #[tokio::test] + async fn grant_durable_fails_closed_when_audit_write_fails() { + // Sprint 24 (closes Sprint 23 council F1): the fail-closed mint must ABORT when its durable + // signed CapabilityGrant cannot be written — no token returned, so no mandate is issued + // whose grant event is not on the chain. Symmetric with revoke_fails_closed above. + let path = std::env::temp_dir().join(format!("mgr-grant-ro-{}.log", std::process::id())); + std::fs::File::create(&path).unwrap(); + let ro = std::fs::OpenOptions::new().read(true).open(&path).unwrap(); + let manager = CapabilityManager::new( + Arc::new(CapabilityStore::new()), + Arc::new(AuditLog::with_file_handle(ro)), + Arc::new(MetricsManager::new()), + ); + + let res = manager.grant_durable( + "test-capsule", + ResourceId::new("localhost://Users/self/Documents/test.txt"), + Action::Read, + TokenConstraints::default(), + None, + None, + ); + assert!( + res.is_err(), + "grant_durable must fail closed when its durable audit write fails — no token issued" + ); + + // A manager with a WRITABLE audit mints successfully and hands back the signed token — the + // emit()? landed, so the grant is on the chain (provability is asserted end-to-end at the + // handler layer, where a durable+signed audit backs export_mandate_receipt_for_capability). + let ok_manager = create_test_manager(); + let token = ok_manager + .grant_durable( + "test-capsule", + ResourceId::new("localhost://Users/self/Documents/test.txt"), + Action::Read, + TokenConstraints::default(), + None, + None, + ) + .expect("a durable mint succeeds when the audit write lands"); + assert!( + token.signature.iter().any(|b| *b != 0), + "the durably-minted token is signed and was handed back" + ); + let _ = std::fs::remove_file(&path); + } + #[tokio::test] async fn test_use_limited_token() { let manager = create_test_manager(); diff --git a/elastos/crates/elastos-runtime/src/capability/mod.rs b/elastos/crates/elastos-runtime/src/capability/mod.rs index 4e124a48..f8390ebe 100644 --- a/elastos/crates/elastos-runtime/src/capability/mod.rs +++ b/elastos/crates/elastos-runtime/src/capability/mod.rs @@ -13,28 +13,37 @@ pub mod receipt; pub mod store; pub mod token; -#[allow(unused_imports)] pub use evaluator::PolicyEvaluator; -#[allow(unused_imports)] pub use intent::{ - check_intent_within_envelope, count_intent_proof, dispatch_standing_act, reconcile, - run_intent_gate, EnvelopeCheck, EnvelopeDenial, IntentDeclarationV1, IntentGateOutcome, - IntentProofSummary, IntentReconciliationV1, ReconciliationStatus, StandingGrantEnvelope, - StandingGrantService, StandingGrantStore, INTENT_DECLARATION_SCHEMA_V1, - INTENT_RECONCILIATION_SCHEMA_V1, + check_intent_freshness, check_intent_within_envelope, count_intent_proof, + dispatch_standing_act, reconcile, run_intent_gate, EnvelopeCheck, EnvelopeDenial, + FreshnessError, IntentDeclarationV1, IntentGateOutcome, IntentProofSummary, + IntentReconciliationV1, ReconciliationStatus, StandingGrantEnvelope, StandingGrantService, + StandingGrantStore, INTENT_DECLARATION_SCHEMA_V1, INTENT_RECONCILIATION_SCHEMA_V1, + MANDATE_DISPATCH_LIMIT, MANDATE_DISPATCH_LIMIT_MAX, MANDATE_DISPATCH_WINDOW_SECS, + MAX_CLOCK_SKEW_SECS, MAX_INTENT_AGE_SECS, }; -#[allow(unused_imports)] pub use manager::CapabilityManager; -#[allow(unused_imports)] pub use pending::{GrantDuration, PendingRequestStore, RequestStatus}; -#[allow(unused_imports)] pub use policy::{ AutoGrantVerifier, DecisionId, GrantProposal, PolicyDecision, PolicyOutcome, PolicyRule, PolicyVerifier, ProposedConstraints, RuleCheck, RulesVerifier, VerifierCheck, }; -#[allow(unused_imports)] pub use receipt::{AffordanceGrantReceiptV1, AFFORDANCE_RECEIPT_SCHEMA_V1}; -#[allow(unused_imports)] pub use store::CapabilityStore; -#[allow(unused_imports)] pub use token::{Action, CapabilityToken, ResourceId, TokenConstraints}; + +/// Longest `responsible_entity` the signed chain accepts. +pub const RESPONSIBLE_ENTITY_MAX_LEN: usize = 256; + +/// The service-layer syntactic bound on a responsible-entity string (council S32 F6): ≤256 chars +/// of DID charset `{alnum : . - _ %}`. Re-applied at EVERY choke point that writes the value +/// verbatim onto the signed chain, so a non-HTTP caller cannot smuggle an unbounded/hostile blob. +/// SYNTACTIC only — never authentication (the HTTP surface layers a stricter `did:` shape check +/// on top). One shared home so the charset cannot drift between choke points. +pub fn responsible_entity_syntax_ok(entity: &str) -> bool { + entity.len() <= RESPONSIBLE_ENTITY_MAX_LEN + && entity + .chars() + .all(|c| c.is_ascii_alphanumeric() || matches!(c, ':' | '.' | '-' | '_' | '%')) +} diff --git a/elastos/crates/elastos-runtime/src/capability/token.rs b/elastos/crates/elastos-runtime/src/capability/token.rs index b998309a..24d3cda1 100644 --- a/elastos/crates/elastos-runtime/src/capability/token.rs +++ b/elastos/crates/elastos-runtime/src/capability/token.rs @@ -137,6 +137,26 @@ impl fmt::Display for Action { } } +impl std::str::FromStr for Action { + type Err = (); + + /// Parse the canonical lowercase action name (the inverse of [`Display`](fmt::Display)) — the + /// ONE place the dispatch gate and any conformance check turn an action STRING back into the + /// enum, so no hand-copied action list can drift from the variants (council S50 guardian F4). + /// Case-insensitive: callers historically lowercased first, so accept mixed case too. + fn from_str(s: &str) -> Result { + match s.to_ascii_lowercase().as_str() { + "read" => Ok(Action::Read), + "write" => Ok(Action::Write), + "execute" => Ok(Action::Execute), + "message" => Ok(Action::Message), + "delete" => Ok(Action::Delete), + "admin" => Ok(Action::Admin), + _ => Err(()), + } + } +} + /// Extensible constraints for capability tokens #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] pub struct TokenConstraints { @@ -476,6 +496,35 @@ mod tests { use super::*; use crate::primitives::time::SecureTimestamp; + /// `FromStr` is the exact inverse of `Display` for every variant (the one action parser), and + /// it is case-insensitive; an unknown action fails closed. This pins the round-trip so the + /// dispatch gate's accepted set can never drift from the enum (S50 guardian F4). + #[test] + fn action_from_str_is_the_inverse_of_display_and_fails_closed() { + use std::str::FromStr; + for a in [ + Action::Read, + Action::Write, + Action::Execute, + Action::Message, + Action::Delete, + Action::Admin, + ] { + assert_eq!(Action::from_str(&a.to_string()), Ok(a), "round-trips: {a}"); + assert_eq!( + Action::from_str(&a.to_string().to_uppercase()), + Ok(a), + "case-insensitive: {a}" + ); + } + assert_eq!( + Action::from_str("negotiate"), + Err(()), + "unknown ⇒ fail-closed" + ); + assert_eq!(Action::from_str(""), Err(())); + } + fn create_test_token() -> CapabilityToken { let signing_key = SigningKey::generate(&mut rand::thread_rng()); let verifying_key = signing_key.verifying_key(); diff --git a/elastos/crates/elastos-runtime/src/primitives/audit.rs b/elastos/crates/elastos-runtime/src/primitives/audit.rs index eb5aec14..2b8feb78 100755 --- a/elastos/crates/elastos-runtime/src/primitives/audit.rs +++ b/elastos/crates/elastos-runtime/src/primitives/audit.rs @@ -27,7 +27,8 @@ use std::collections::VecDeque; use std::fs::{File, OpenOptions}; use std::io::{BufRead, BufReader, BufWriter, Write}; use std::path::{Path, PathBuf}; -use std::sync::{Mutex, RwLock}; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::{Condvar, Mutex, RwLock}; use super::time::SecureTimestamp; use crate::capability::token::{Action, ResourceId, TokenId}; @@ -61,8 +62,61 @@ fn compute_record_hash(seq: u64, prev_hash: &[u8; 32], event_json: &[u8]) -> [u8 h.finalize().into() } +/// THE one canonicalization recipe every verifier uses: re-serialize the deserialized event with +/// this crate's serde and recompute the record hash over it. Shared by [`AuditLog::verify_chain`] +/// and [`verify_mandate_receipt`] so the meaning of "verified" can never quietly fork between the +/// on-disk walker and the portable-receipt walker (their LINKAGE policies differ by design — a +/// chain walk is contiguous, a Capability-scoped receipt is a bound selection — but the bytes +/// each record is hashed over must be identical). `Err` carries the raw serde error. +fn recompute_record_hash(rec: &ChainedRecord, prev_hash: &[u8; 32]) -> Result<[u8; 32], String> { + let event_json = serde_json::to_string(&rec.event).map_err(|e| e.to_string())?; + Ok(compute_record_hash( + rec.seq, + prev_hash, + event_json.as_bytes(), + )) +} + +/// Domain separator for the mandate-receipt SET binding — distinct from [`AUDIT_RECORD_DOMAIN`] so a +/// set-binding signature can never be confused for (or replayed as) a per-record signature. +const MANDATE_RECEIPT_BINDING_DOMAIN: &[u8] = b"elastos.runtime/mandate-receipt-set/v1"; + +/// The canonical bytes an issuing runtime signs to BIND the exact ordered record set of a receipt: +/// the scope, the record count, and every `record_hash` in order. Recomputable by any verifier from +/// the receipt alone, so a signature over it makes the SET tamper-evident — adding, dropping, or +/// reordering any record changes these bytes. This closes the keyless "a holder trims a use in +/// transit" gap that a per-record filter cannot: each `record_hash` already commits to its record's +/// `(seq, prev_hash, event)`, so binding the ordered hash list fixes the whole membership. It does +/// NOT bind against the key-holding issuer itself (which can sign any set) — the same tamper-evident, +/// not tamper-proof, bound the chain's signing key carries everywhere. +fn mandate_receipt_binding_message( + scope: &MandateReceiptScope, + records: &[ChainedRecord], +) -> Vec { + let mut msg = + Vec::with_capacity(MANDATE_RECEIPT_BINDING_DOMAIN.len() + 32 + records.len() * 64); + msg.extend_from_slice(MANDATE_RECEIPT_BINDING_DOMAIN); + match scope { + MandateReceiptScope::Contiguous => msg.push(0u8), + MandateReceiptScope::Capability { token_id } => { + msg.push(1u8); + msg.extend_from_slice(&(token_id.len() as u64).to_be_bytes()); + msg.extend_from_slice(token_id.as_bytes()); + } + } + msg.extend_from_slice(&(records.len() as u64).to_be_bytes()); + for record in records { + // `record_hash` is a fixed-width hex string (64 chars); position + count fix the order. + msg.extend_from_slice(record.record_hash.as_bytes()); + } + msg +} + /// One tamper-evident, hash-chained, signed audit record as persisted to disk (one JSON object per /// line). The on-disk format; the in-memory ring buffer keeps bare [`AuditEvent`]s for fast reads. +/// +/// FROZEN serialized shape — same rule as [`AuditEvent`]: verification re-serializes and +/// re-hashes these records, so field order/names must never change for existing chains to verify. #[derive(Debug, Clone, Serialize, Deserialize)] pub struct ChainedRecord { /// Monotonic sequence number (first record = 1). A gap or repeat is tamper-evidence. @@ -79,6 +133,332 @@ pub struct ChainedRecord { pub sig: String, } +/// Schema tag for [`MandateReceipt`]; the verifier fail-closes on any other value. +pub const MANDATE_RECEIPT_SCHEMA: &str = "elastos.mandate_receipt/v1"; + +/// What a [`MandateReceipt`] covers — which determines how it is verified. +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(tag = "kind", rename_all = "snake_case")] +pub enum MandateReceiptScope { + /// A CONTIGUOUS run of the chain (whole chain or a `seq` range). Verified with the contiguity + /// check: each record links the prior and `seq` increments by 1, so nothing INTERIOR was dropped. + Contiguous, + /// EVERY record this runtime holds for ONE capability `token_id` — a FILTERED, non-contiguous + /// view (a delegation's records are interleaved with others in the chain, so contiguity does NOT + /// apply). Verified instead by requiring that every record carries this `token_id`, exactly one + /// is the `CapabilityGrant` (the mandate itself), and the records are in strictly ascending + /// `seq` (no duplicate or reorder). This is the per-delegation receipt shape. + /// + /// COMPLETENESS is bounded, and the bound differs by WHO the adversary is: + /// - Against any HOLDER in transit (relay, custodian, the audited party): the issuer's + /// [`MandateReceipt::set_binding`] signature fixes the exact record set, so dropping, + /// adding, or reordering a use/revoke is DETECTED (`set_binding_ok` fails). + /// - Against the key-holding ISSUER itself: NOT provable — a compromised runtime can sign a + /// selective set. This is the same tamper-evident-not-tamper-proof bound the chain's signing + /// key carries everywhere; unlike a `Contiguous` receipt (whose linkage would break on an + /// interior drop), a `Capability` receipt does not prove the issuer omitted nothing at export. + Capability { token_id: String }, +} + +/// A PORTABLE, self-contained proof that a set of audit records were authorized and recorded under +/// one signer — verifiable by a THIRD PARTY (an auditor, insurer, counterparty) with NO runtime, NO +/// `AuditLog`, and NO disk access: just this JSON document and [`verify_mandate_receipt`]. This is +/// the "admissible receipt" product primitive for Flint — it turns the tamper-evident chain from an +/// internal integrity feature into an artifact you can hand someone off-box. By convention +/// `records[0]` is the authorization (the mandate) and the rest are the actions taken under it, in +/// ascending `seq`. The verifier proves each record is individually signed + untampered, that the +/// set satisfies its [`scope`](MandateReceipt::scope) rule (contiguity for `Contiguous`; token +/// binding + single grant + strict order for `Capability`), and — via +/// [`set_binding`](MandateReceipt::set_binding) — that no HOLDER altered the record set in transit. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct MandateReceipt { + /// Schema tag; always `elastos.mandate_receipt/v1`. + pub schema: String, + /// Hex of the ed25519 verifying key the records are signed under (the issuing runtime's DID key). + /// + /// SELF-ASSERTED — READ THIS: a `verified == true` verdict authenticates the records against + /// THIS key only. It does NOT prove the key is who you think it is: anyone can mint a keypair, + /// fabricate a "mandate + actions" chain, sign it, and produce a receipt that verifies against + /// its own key. A consumer MUST pin the expected signer out-of-band (pass `expected_signer_hex` + /// to [`verify_mandate_receipt`], or compare this field to a DID key it trusts). Two further + /// caveats travel with this artifact (same as the chain it comes from): (a) records dropped off + /// the END of the exported range are undetectable without an external anchor — the receipt + /// proves what it contains is a contiguous run, not that it is COMPLETE; (b) a live-compromised + /// runtime holds the signing key and can sign a fabricated receipt. Tamper-EVIDENT, not + /// tamper-proof. + pub signer_public_key_hex: String, + /// What this receipt covers — selects the verification model (contiguity vs per-capability). + #[serde(default = "default_receipt_scope")] + pub scope: MandateReceiptScope, + /// The signed, hash-chained records, ascending `seq`. `records[0]` = mandate, rest = actions. + pub records: Vec, + /// Ed25519 signature (base64) by the issuing runtime over + /// [`mandate_receipt_binding_message`] — it BINDS the exact ordered record set (scope + count + + /// each `record_hash`), so no HOLDER in transit can add, drop, or reorder a record undetectably. + /// REQUIRED for `Capability` scope (whose membership is otherwise a keyless filter a holder could + /// trim); optional for legacy `Contiguous` receipts, where linkage already fixes the interior. + /// `None` only for a memory-only/unsigned log. This stops HOLDERS, not the key-holding issuer: + /// a compromised runtime can still sign a selective set (tamper-evident, not tamper-proof). + #[serde(default)] + pub set_binding: Option, +} + +fn default_receipt_scope() -> MandateReceiptScope { + MandateReceiptScope::Contiguous +} + +/// The result of independently verifying a [`MandateReceipt`]. Every boolean is a distinct failure +/// mode so a consumer can see WHY: a tampered event breaks `hashes_ok`, a forged/wrong-key signature +/// breaks `signatures_ok`, a dropped/reordered record breaks `chain_linkage_ok`. +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub struct MandateReceiptVerdict { + /// AUTHENTIC — the single bit an auditor acts on. True ONLY when the receipt is + /// `structurally_valid` AND its embedded signer matches the caller-PINNED expected signer. + /// `false` whenever no expected signer was pinned: you CANNOT authenticate a self-asserted + /// receipt without an out-of-band trust anchor (an attacker's self-signed receipt is + /// structurally valid too — see [`MandateReceipt`]). + pub authenticated: bool, + /// Structurally valid under the receipt's OWN embedded key: every hash recomputes, every + /// signature verifies, records are contiguous. This is NOT authenticity — use it only for + /// display ("signed by "), never as the trust decision. Prefer [`authenticated`]. + pub structurally_valid: bool, + /// Whether the receipt's embedded signer equals the caller-pinned expected signer. `None` when + /// the caller pinned no expected signer (so authenticity could not be decided). + pub signer_matches_expected: Option, + /// True iff `records[0]` is the genesis-anchored start of the chain (`seq == 1`, `prev_hash` all + /// zero) — so the receipt proves the run FROM THE BEGINNING. (Front-truncation is otherwise + /// undetectable; END-truncation still needs an external head anchor — see [`MandateReceipt`].) + /// N/A for `Capability` scope: a mandate's grant sits mid-chain after unrelated events, so this + /// is expected to be `false` for a legitimate per-capability receipt — do not treat it as a + /// completeness or suspicion signal there (use `scope_ok` + `set_binding_ok` instead). + pub starts_at_genesis: bool, + /// How many records were checked. + pub records: usize, + /// The signer the receipt claims to be signed under (echoed so a consumer can pin it). + pub signer_public_key_hex: String, + /// Every record's `record_hash` recomputes from its own contents (no event was edited). + pub hashes_ok: bool, + /// Every record is ed25519-signed and verifies against the signer key over its `record_hash`. + pub signatures_ok: bool, + /// The records form a contiguous run: `seq` increments by 1 and each `prev_hash` links the prior. + /// (Reported for every receipt; only REQUIRED for a `Contiguous`-scope receipt.) + pub chain_linkage_ok: bool, + /// The scope's structural rule holds. For `Contiguous` this is `chain_linkage_ok` (a completeness + /// statement: nothing interior was dropped). For `Capability` it is BINDING + shape, NOT + /// completeness: every record carries the target `token_id`, exactly one is the grant, and the + /// records are in strictly ascending `seq`. A `Capability` `scope_ok == true` does NOT assert no + /// use was omitted at export by the issuer — see [`MandateReceiptScope::Capability`]; holder-side + /// omission is caught separately by `set_binding_ok`. + pub scope_ok: bool, + /// The issuer's [`MandateReceipt::set_binding`] signature verifies over the exact ordered record + /// set — so no HOLDER added, dropped, or reordered a record in transit. REQUIRED (must be `true`) + /// for `Capability` scope; for `Contiguous` it is `true` when absent (linkage already binds the + /// interior) and verified when present. Does not bind against the key-holding issuer itself. + pub set_binding_ok: bool, + /// The first structural failure (bad schema/hex, wrong key length, empty receipt), if any. + pub error: Option, +} + +impl MandateReceiptVerdict { + fn failed(signer_public_key_hex: String, error: impl Into) -> Self { + MandateReceiptVerdict { + authenticated: false, + structurally_valid: false, + signer_matches_expected: None, + starts_at_genesis: false, + records: 0, + signer_public_key_hex, + hashes_ok: false, + signatures_ok: false, + chain_linkage_ok: false, + scope_ok: false, + set_binding_ok: false, + error: Some(error.into()), + } + } +} + +/// STANDALONE verification of a [`MandateReceipt`] — pure, no `self`, no I/O, no runtime. Re-derives +/// each `record_hash` exactly as the chain did (`compute_record_hash`), checks the ed25519 signature +/// over it against the receipt's own signer key, and checks contiguity. Mirrors +/// [`AuditLog::verify_chain`]'s recipe byte-for-byte, minus the disk. +/// +/// AUTHENTICITY REQUIRES PINNING. `expected_signer_hex` is the caller's out-of-band trust anchor — +/// the DID key it already trusts for the issuing runtime. The result's `authenticated` bit is true +/// ONLY when the receipt is structurally sound AND its embedded signer equals that pinned key. Pass +/// `None` only when you deliberately want a STRUCTURAL check for display (never a trust decision): +/// an attacker can self-sign a fabricated receipt that is `structurally_valid` under its own key, so +/// `authenticated` is `false` without a pin. The record SET is also bound by the issuer's +/// `set_binding` signature (`set_binding_ok`), so a HOLDER cannot add/drop/reorder a record in +/// transit — REQUIRED for `Capability` scope. Residual caveats (carried from the chain): a +/// `Contiguous` receipt proves its records are a contiguous run but end-truncation still needs an +/// external head anchor (`starts_at_genesis` covers only the front); a `Capability` receipt's +/// completeness holds only against holders, not the key-holding issuer; and verification re-serializes +/// events with this crate's serde, so a third party must use a byte-compatible encoder. +pub fn verify_mandate_receipt( + receipt: &MandateReceipt, + expected_signer_hex: Option<&str>, +) -> MandateReceiptVerdict { + let signer = receipt.signer_public_key_hex.clone(); + if receipt.schema != MANDATE_RECEIPT_SCHEMA { + return MandateReceiptVerdict::failed( + signer, + format!( + "unexpected schema {:?} (want {MANDATE_RECEIPT_SCHEMA})", + receipt.schema + ), + ); + } + if receipt.records.is_empty() { + return MandateReceiptVerdict::failed(signer, "receipt has no records"); + } + // Decode the self-contained signer key — the only key material the verifier needs. + let vk_bytes = match hex::decode(receipt.signer_public_key_hex.trim()) { + Ok(bytes) => bytes, + Err(e) => return MandateReceiptVerdict::failed(signer, format!("bad signer key hex: {e}")), + }; + let vk_array: [u8; 32] = match vk_bytes.as_slice().try_into() { + Ok(array) => array, + Err(_) => return MandateReceiptVerdict::failed(signer, "signer key is not 32 bytes"), + }; + let vk = match VerifyingKey::from_bytes(&vk_array) { + Ok(key) => key, + Err(e) => return MandateReceiptVerdict::failed(signer, format!("invalid signer key: {e}")), + }; + + let mut hashes_ok = true; + let mut signatures_ok = true; + let mut chain_linkage_ok = true; + + for (index, record) in receipt.records.iter().enumerate() { + // Contiguity: each record after the first must link the prior by hash AND increment seq by 1. + if index > 0 { + let prior = &receipt.records[index - 1]; + if record.prev_hash != prior.record_hash || record.seq != prior.seq.saturating_add(1) { + chain_linkage_ok = false; + } + } + // Internal integrity: recompute the record hash from the record's OWN contents. + let prev_hash: [u8; 32] = match hex::decode(&record.prev_hash) + .ok() + .and_then(|bytes| bytes.try_into().ok()) + { + Some(array) => array, + None => { + hashes_ok = false; + signatures_ok = false; + continue; + } + }; + let computed = match recompute_record_hash(record, &prev_hash) { + Ok(hash) => hash, + Err(e) => { + return MandateReceiptVerdict::failed( + signer, + format!("seq {}: re-serialize event: {e}", record.seq), + ) + } + }; + match hex::decode(&record.record_hash) { + Ok(claimed) if claimed.as_slice() == computed.as_slice() => {} + _ => hashes_ok = false, + } + // Signature: a mandate receipt MUST be ed25519-signed (never `alg="none"`), verifying over + // the recomputed hash against the receipt's own signer key. + if record.alg != AUDIT_SIG_ALG_ED25519 { + signatures_ok = false; + continue; + } + let sig_ok = BASE64 + .decode(record.sig.trim()) + .ok() + .and_then(|bytes| Signature::from_slice(&bytes).ok()) + // STRICT verification (council S49 red-team F3): reject malleated-S and + // small-order keys, matching the intent path's own posture — two conforming + // verifiers must never disagree on a malleated signature. + .map(|signature| vk.verify_strict(&computed, &signature).is_ok()) + .unwrap_or(false); + if !sig_ok { + signatures_ok = false; + } + } + + // The scope's completeness/binding rule. Contiguous ⇒ nothing interior dropped (linkage); + // Capability ⇒ every record is bound to the target token_id and exactly one is the grant, so a + // record from a DIFFERENT delegation can't be smuggled in and the mandate itself is present. + let scope_ok = match &receipt.scope { + MandateReceiptScope::Contiguous => chain_linkage_ok, + MandateReceiptScope::Capability { token_id } => { + let all_bound = receipt + .records + .iter() + .all(|record| record.event.capability_token_id() == Some(token_id.as_str())); + let grant_count = receipt + .records + .iter() + .filter(|record| record.event.is_capability_grant()) + .count(); + // Strictly ascending, unique `seq`: a bundle-only guard against a duplicated or + // reordered record inflating/misrepresenting the action set. + let strictly_ordered = receipt + .records + .windows(2) + .all(|pair| pair[1].seq > pair[0].seq); + all_bound && grant_count == 1 && strictly_ordered + } + }; + // SET BINDING: the issuer's signature over the ordered record set (scope + count + record + // hashes). It makes membership tamper-EVIDENT against any HOLDER — a dropped/added/reordered + // record changes the signed message. REQUIRED for `Capability`; for `Contiguous` the linkage + // already fixes the interior, so a binding is optional but MUST verify when present. + let set_binding_ok = match &receipt.set_binding { + Some(sig_b64) => BASE64 + .decode(sig_b64.trim()) + .ok() + .and_then(|bytes| Signature::from_slice(&bytes).ok()) + .map(|signature| { + // Strict for the same reason as the per-record sigs (S49 red-team F3). + vk.verify_strict( + &mandate_receipt_binding_message(&receipt.scope, &receipt.records), + &signature, + ) + .is_ok() + }) + .unwrap_or(false), + None => matches!(receipt.scope, MandateReceiptScope::Contiguous), + }; + let structurally_valid = hashes_ok && signatures_ok && scope_ok && set_binding_ok; + // Authenticity requires the caller's out-of-band pin: the embedded signer must equal a key the + // consumer already trusts. Without a pin we CANNOT authenticate — an attacker self-signs too. + let signer_matches_expected = expected_signer_hex.map(|expected| { + expected + .trim() + .eq_ignore_ascii_case(receipt.signer_public_key_hex.trim()) + }); + let authenticated = structurally_valid && signer_matches_expected == Some(true); + // Genesis anchor: records[0] is the true start of the chain (front-truncation guard). + let first = &receipt.records[0]; + let starts_at_genesis = first.seq == 1 + && hex::decode(&first.prev_hash) + .map(|bytes| bytes.len() == 32 && bytes.iter().all(|byte| *byte == 0)) + .unwrap_or(false); + + MandateReceiptVerdict { + authenticated, + structurally_valid, + signer_matches_expected, + starts_at_genesis, + records: receipt.records.len(), + signer_public_key_hex: signer, + hashes_ok, + signatures_ok, + chain_linkage_ok, + scope_ok, + set_binding_ok, + error: None, + } +} + /// Errors from [`AuditLog::emit`]. A custody-relevant caller MUST fail its operation closed on any /// of these (the record could not be durably committed to the tamper-evident log). #[derive(Debug)] @@ -105,13 +485,58 @@ impl std::error::Error for AuditError {} /// Mutable hash-chain head, guarded by a `Mutex` so `emit(&self, ..)` stays `&self`. struct ChainState { - /// `seq` of the last DURABLY-committed record (0 = none yet; next record is `last_seq + 1`). + /// `seq` of the last APPENDED record (0 = none yet; next record is `last_seq + 1`). On a + /// file-backed log this advances once the record's bytes are flushed to the OS (append order + /// is the chain order); DURABILITY is tracked separately by [`FlushState::durable_seq`] — an + /// `emit` does not return `Ok` until its seq is durable (group commit, S51). last_seq: u64, - /// `record_hash` of the last committed record (genesis = zeros). The next record's `prev_hash`. + /// `record_hash` of the last appended record (genesis = zeros). The next record's `prev_hash`. prev_hash: [u8; 32], } -/// Audit event types +/// Group-commit durability state for a file-backed log (Sprint 51 — Track C2). MEASURED motivation +/// (`benches/audit_emit.rs`, the S51 decision run): one fsync per record costs ~950 µs — a ~1.1k +/// emits/s global ceiling, ~430× the CPU cost of the emit itself — and every concurrent emitter +/// serialized behind it (magnitudes are box-dependent; re-run the bench on the target). The +/// group commit lets N concurrent emits share ONE fsync: each emitter appends its record (ordered, +/// under the chain lock), then waits until a flusher's fsync covers its seq. THE CONTRACT IS +/// UNCHANGED: `emit` returns `Ok` only after ITS record is durable on disk — batching moves the +/// fsync, never the promise. Single-threaded emits still pay one fsync each (nothing to coalesce); +/// the ceiling lifts with CONCURRENCY, which is exactly the regime the server's per-request +/// custody emits are in. +struct FlushState { + /// Highest seq durably on disk (covered by a completed fsync). + durable_seq: u64, + /// A flusher's fsync is currently in flight (exactly one at a time). + flushing: bool, + /// Set on the FIRST durable-write or fsync failure and never cleared: the log refuses every + /// subsequent emit (fail-closed). After a failed write/fsync the on-disk suffix is UNKNOWN + /// (the bytes may or may not land), so "retry the same seq" — the pre-S51 behavior — could + /// append a DUPLICATE seq after a half-landed one and corrupt the chain for verifiers. The + /// write-failure arm poisons while STILL HOLDING the chain lock and `emit` re-checks under it + /// (council S51 guardian F1 / red-team F2), so an emit queued on the chain lock during the + /// failure can never re-derive the failed seq and append behind the fragment. A poisoned log + /// is an operator incident: restart re-opens from the durable prefix (a torn + /// never-acknowledged tail is quarantined at open — `quarantine_torn_tail`; the verified open + /// then re-verifies the whole remaining chain). + poisoned: Option, +} + +/// Audit event types. +/// +/// # The serialized shape of EVERY variant is FROZEN +/// +/// Chain verification ([`AuditLog::verify_chain`], [`verify_mandate_receipt`]) RE-SERIALIZES each +/// deserialized event and recomputes its hash, so the serialized bytes of every variant — field +/// ORDER, field NAMES, omission rules — are load-bearing for every signed chain and every portable +/// receipt already in the world. Reordering, renaming, or inserting a field in ANY variant silently +/// breaks verification of all pre-existing records. +/// +/// To extend a variant: append the new field LAST with +/// `#[serde(default, skip_serializing_if = "Option::is_none")]` so a pre-existing record (no field +/// ⇒ `None`) re-serializes byte-identically, and add a byte-identity ratchet test beside +/// `rail_ref_is_present_when_set_and_omitted_for_back_compat`. The `responsible_entity`, +/// `rail_ref`, and `grant_digest` fields below are the worked examples. #[derive(Debug, Clone, Serialize, Deserialize)] #[serde(tag = "type", rename_all = "snake_case")] pub enum AuditEvent { @@ -148,6 +573,13 @@ pub enum AuditEvent { resource: String, action: String, expiry: Option, + /// The RESPONSIBLE ENTITY (Sprint 32): the operator/legal entity DID accountable for every + /// act under this grant — the EU-AI-Act liability binding, hash-linked and signed into the + /// chain (and therefore into the portable MandateReceipt). `skip_serializing_if` is + /// LOAD-BEARING: chain verification RE-SERIALIZES deserialized events, so a pre-S32 record + /// (no field ⇒ None) must re-serialize byte-identically or every old chain breaks. + #[serde(default, skip_serializing_if = "Option::is_none")] + responsible_entity: Option, }, /// Capability revoked @@ -165,6 +597,18 @@ pub enum AuditEvent { resource: String, action: String, success: bool, + /// The rail's reference for an act that settled on an external rail (Sprint 34): for a + /// `runtime.pay` act it is the payment/on-chain reference (e.g. a DRM buy's tx hash + + /// `operative:tokenId`), sanitized and bounded. `None` for every non-rail act. This is + /// the on-chain truth the portable receipt carries — WHICH tx settled the mandate's + /// payment — beyond the amount already in `input_hash`. + /// + /// BACK-COMPAT IS LOAD-BEARING (mirrors S32 `responsible_entity`): appended LAST with + /// `#[serde(default, skip_serializing_if = "Option::is_none")]`, so a pre-S34 + /// `CapabilityUse` (no field ⇒ None) re-serializes byte-identically and every pre-S34 + /// signed chain still verifies. + #[serde(default, skip_serializing_if = "Option::is_none")] + rail_ref: Option, }, /// Content fetched via elastos:// @@ -490,11 +934,39 @@ pub struct AuditLog { echo_stdout: bool, /// In-memory buffer of recent events (ring buffer) memory_buffer: RwLock>, - /// Hash-chain head (seq + prev_hash), advanced only on a DURABLY-committed record. + /// Hash-chain head (seq + prev_hash) — see [`ChainState`] for the append-vs-durable split. chain: Mutex, /// ed25519 signer for the chain. `None` ⇒ records carry `alg = "none"` (chain only, no /// non-repudiation). A persisted, dedicated key (NOT a fresh in-memory one) when file-backed. signer: Option, + /// Group-commit durability tracker (S51), file-backed logs only. LOCK ORDER: `chain` → `writer` + /// during append; `flush.0` alone, then `writer` alone, during a flush — the flusher NEVER + /// holds `chain`, so appends and fsyncs overlap only at the writer mutex. + flush: Option<(Mutex, Condvar)>, + /// Highest seq whose bytes are flushed to the OS (BufWriter flush complete). Written under the + /// chain lock; read by the flusher (without `chain`) to know what seq its fsync will cover. + written_seq: AtomicU64, + /// Highest seq the tail-truncation head anchor has recorded. Its own mutex (never nested with + /// the others) so the anchor write runs OFF the flush critical path and can never hold up the + /// waiters a flush just released. Guarded-monotonic: a flusher anchors only a cover above the + /// recorded high, so late/overlapping flushers can never regress the anchor. + anchored_seq: Mutex, + /// A CLONED fd of the log file, used ONLY for `sync_all` (never written). MEASURED necessity + /// (the second S51 cut): fsyncing through the writer mutex convoyed every concurrent appender + /// behind the ~1 ms fsync (an appender holds `chain` while waiting on `writer`), collapsing + /// group-commit batches to ~1 record — SLOWER than the serial baseline. `fsync` commits the + /// INODE, not the fd, so syncing this clone durably commits every byte the appenders already + /// flushed to the OS, while they keep appending through the writer. `None` only if the clone + /// failed at open (then the flusher falls back to fsync-under-the-writer-mutex: correct, + /// convoy-slow). + sync_handle: Option, + /// Held for the log's lifetime (S52, closing the S51 red-team dual-writer residual): an + /// exclusive advisory flock on `.lock`, the SAME single-opener discipline the spend meter + /// and payment ledger hold. Two live `AuditLog`s on one file each keep independent chain heads + /// and mint the same seqs — interleaved appends corrupt the chain on disk, and under the S51 + /// group commit one instance's fsync even covers the sibling's uncoordinated bytes. Now a + /// second opener FAILS fail-closed (`WouldBlock`) instead. Unix only, like the meter's. + _lock_file: Option, } impl AuditLog { @@ -511,9 +983,27 @@ impl AuditLog { prev_hash: genesis_prev_hash(), }), signer: None, + flush: None, + written_seq: AtomicU64::new(0), + anchored_seq: Mutex::new(0), + sync_handle: None, + _lock_file: None, } } + /// Fresh group-commit state for a file-backed log resuming at `resumed_seq` (everything already + /// on disk is durable by definition — it was read back). + fn fresh_flush_state(resumed_seq: u64) -> Option<(Mutex, Condvar)> { + Some(( + Mutex::new(FlushState { + durable_seq: resumed_seq, + flushing: false, + poisoned: None, + }), + Condvar::new(), + )) + } + /// Create an audit log that writes to the given path, hash-chained and ed25519-signed. /// /// The signing key is loaded from (or, first time, generated into) a sibling `.signing-key` @@ -530,17 +1020,65 @@ impl AuditLog { std::fs::create_dir_all(parent)?; } + // SINGLE-OPENER (S52): take the exclusive advisory flock FIRST — before the quarantine or + // any read — so a second live opener fails here fail-closed rather than two instances + // minting the same seqs (or both mutating a torn tail). Held for the log's lifetime; see + // `_lock_file`. Mirrors `SpendMeter::open_durable` (council S28 F4 discipline). + #[cfg(unix)] + let lock_file = { + use std::os::unix::io::AsRawFd as _; + let lock_path = sibling(&path, "lock"); + let f = OpenOptions::new() + .create(true) + .truncate(false) // the lock file carries no content; never disturb it + .write(true) + .open(&lock_path)?; + let rc = unsafe { libc::flock(f.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) }; + if rc != 0 { + return Err(std::io::Error::new( + std::io::ErrorKind::WouldBlock, + "audit log is already open elsewhere (single-opener, fail-closed)", + )); + } + Some(f) + }; + #[cfg(not(unix))] + let lock_file = None; + + // Quarantine a torn (provably never-acknowledged) trailing fragment BEFORE resuming, so a + // crash mid-writeback re-opens from the intact durable prefix instead of refusing (verified + // mode) or appending onto the fragment (plain mode) — see `quarantine_torn_tail`. + quarantine_torn_tail(&path)?; + // Resume the chain head from any existing records (append-only continuity across restarts). let chain = resume_chain_state(&path); // Open APPEND-ONLY: never truncate or seek; the chain is the integrity, the OS append is the // ordering. (`append(true)` forces every write to EOF even under concurrent writers.) let file = OpenOptions::new().create(true).append(true).open(&path)?; + // The fsync-only clone (see `sync_handle`) — taken before the fd moves into the BufWriter. + let sync_handle = match file.try_clone() { + Ok(h) => Some(h), + Err(e) => { + tracing::warn!( + "audit log fd clone failed ({e}) — group-commit falls back to fsync under \ + the writer lock (correct, slower under concurrency)" + ); + None + } + }; let writer = BufWriter::new(file); // Load-or-create the dedicated, persisted signing key alongside the log. let signer = load_or_create_signer(&path)?; + let resumed_seq = chain.last_seq; + // Seed the anchor high-water from the ON-DISK anchor too (council S51 guardian F5): a log + // reopened (unverified) after truncation resumes at a LOWER seq, and seeding from + // resumed_seq alone would let the first flush overwrite the anchor DOWNWARD — destroying + // the very truncation evidence a later verified open would have caught. Best-effort read + // (an unreadable anchor seeds from the resumed head; the verified open still fail-closes). + let disk_anchor = read_head_anchor(&path).ok().flatten().unwrap_or(0); Ok(Self { writer: Some(Mutex::new(writer)), log_path: Some(path), @@ -548,6 +1086,11 @@ impl AuditLog { memory_buffer: RwLock::new(VecDeque::with_capacity(MAX_MEMORY_EVENTS)), chain: Mutex::new(chain), signer: Some(signer), + flush: Self::fresh_flush_state(resumed_seq), + written_seq: AtomicU64::new(resumed_seq), + anchored_seq: Mutex::new(resumed_seq.max(disk_anchor)), + sync_handle, + _lock_file: lock_file, }) } @@ -597,13 +1140,16 @@ impl AuditLog { self.echo_stdout = echo; } - /// Test-only: wrap an already-open file handle as a file-backed log, so a - /// test can force a durable-write failure (e.g. a read-only fd) and prove a - /// fail-closed caller (`emit` + `?`) aborts instead of silently completing - /// (G8a). Chain starts at genesis and is unsigned (`signer: None`) — this - /// seam exercises the write/IO failure path, not signature semantics. - #[cfg(test)] - pub(crate) fn with_file_handle(file: File) -> Self { + /// TEST SEAM (never a production constructor): wrap an already-open file + /// handle as a file-backed log, so a test can force a durable-write failure + /// (e.g. a read-only fd) and prove a fail-closed caller (`emit` + `?`) + /// aborts instead of silently completing (G8a). Chain starts at genesis and + /// is unsigned (`signer: None`) — this seam exercises the write/IO failure + /// path, not signature semantics. `pub` so downstream crates' ratchets + /// (e.g. the spend-budget attest-failure rollback, council S28 F2) can + /// inject the same failure; production wiring uses `with_file*` only. + pub fn with_file_handle(file: File) -> Self { + let sync_handle = file.try_clone().ok(); Self { writer: Some(Mutex::new(BufWriter::new(file))), log_path: None, @@ -614,6 +1160,12 @@ impl AuditLog { prev_hash: genesis_prev_hash(), }), signer: None, + flush: Self::fresh_flush_state(0), + written_seq: AtomicU64::new(0), + anchored_seq: Mutex::new(0), + sync_handle, + // The test seam has no path to lock (and forces failures on purpose) — no flock. + _lock_file: None, } } @@ -632,15 +1184,39 @@ impl AuditLog { /// FAIL-LOUD + FAIL-CLOSED: on a serialization or durable-write failure this returns `Err` AND /// logs at `error!`. A custody-relevant caller MUST propagate the `Err` and fail its operation /// closed (the open/grant did not make it into the custody trail). Best-effort callers may - /// ignore the result; the loud log still fires. The hash-chain head only advances on a record - /// that was durably written + `fsync`ed, so a failed write does not corrupt the chain. + /// ignore the result; the loud log still fires. + /// + /// DURABILITY CONTRACT (unchanged by the S51 group commit): `Ok(())` means THIS record is + /// durably on disk (written + `fsync`ed). What changed is HOW: concurrent emits append in + /// chain order, then share fsyncs — one flusher's `sync_all` covers every record appended + /// before it, so N concurrent emitters pay ~1 fsync instead of N (measured ~430× per-record + /// fsync cost, S51 decision run; `benches/audit_emit.rs`). A failed append or fsync POISONS + /// the log: the failing emit and every later one return `Err` (after a failed write/fsync the + /// on-disk suffix is unknown, so retrying a seq could append a duplicate after a half-landed + /// record and corrupt the chain — refusing is the only honest posture; a restart re-verifies + /// the durable prefix, quarantining a torn never-acknowledged tail — see + /// `quarantine_torn_tail`). The inverse direction is inherent to fsync semantics + /// and unchanged: an emit that returned `Err` MAY still have landed on disk — callers already + /// treat `Err` as "act did not happen", and an extra durable record is an over-record, never a + /// lost one. pub fn emit(&self, event: AuditEvent) -> Result<(), AuditError> { let event_json = serde_json::to_string(&event).map_err(|e| AuditError::Serialize(e.to_string()))?; - // Take the chain lock for the whole compute→write→advance critical section so `seq`/ - // `prev_hash` cannot interleave across threads. + // Fast-path refusal on a poisoned log (an authoritative re-check runs UNDER the chain + // lock below — this one just refuses cheap, before serializing the event). + self.check_not_poisoned()?; + + // APPEND PHASE — the chain lock serializes seq assignment, signing, and the ORDERED append + // (chain order IS append order), but no longer spans the fsync. let mut chain = self.chain.lock().map_err(|_| AuditError::Lock)?; + // AUTHORITATIVE poison check, under the chain lock (council S51 guardian F1): a write + // failure poisons BEFORE releasing the chain lock (below), so an emit that was queued on + // the chain lock while another emit's append failed re-checks HERE and refuses — it can + // never re-derive the failed seq and append after half-landed bytes (the duplicate-seq + // corruption this closes). Lock order chain→flush is safe: nothing acquires `chain` while + // holding the flush lock. + self.check_not_poisoned()?; let seq = chain.last_seq + 1; let prev_hash = chain.prev_hash; let record_hash = compute_record_hash(seq, &prev_hash, event_json.as_bytes()); @@ -667,44 +1243,49 @@ impl AuditLog { let line = serde_json::to_string(&record).map_err(|e| AuditError::Serialize(e.to_string()))?; - if self.echo_stdout { - println!("[AUDIT] {}", line); - } - - // Durably commit BEFORE advancing the chain head. A failed write leaves `seq`/`prev_hash` - // untouched, so the next emit retries the same seq — no gap, no silent loss. if let Some(writer) = &self.writer { - let mut w = writer.lock().map_err(|_| AuditError::Lock)?; - writeln!(w, "{}", line).map_err(|e| { + // Append + flush THIS record's bytes to the OS, still under the chain lock (order). + let write_res = { + let mut w = writer.lock().map_err(|_| AuditError::Lock)?; + writeln!(w, "{}", line).and_then(|_| w.flush()) + }; + if let Err(e) = write_res { tracing::error!("AUDIT durable-write failed (seq {seq}): {e}"); - AuditError::Io(e.to_string()) - })?; - w.flush().map_err(|e| { - tracing::error!("AUDIT flush failed (seq {seq}): {e}"); - AuditError::Io(e.to_string()) - })?; - // fsync: the record must survive a crash/power loss to be a custody record at all. - w.get_ref().sync_all().map_err(|e| { - tracing::error!("AUDIT sync_all failed (seq {seq}): {e}"); - AuditError::Io(e.to_string()) - })?; + // Poison while STILL HOLDING the chain lock (guardian F1): the next emit queued on + // the chain lock must see the poison before it can compute this same seq and + // append after our half-landed bytes. chain→flush nesting is acyclic (no path + // takes `chain` while holding the flush lock). + self.poison(format!("durable write failed at seq {seq}: {e}")); + drop(chain); + return Err(AuditError::Io(e.to_string())); + } + // The bytes are in the OS: advance the APPEND head and publish the flusher's cover + // point. Durability is NOT yet promised — that is wait_durable's job. + chain.last_seq = seq; + chain.prev_hash = record_hash; + self.written_seq.store(seq, Ordering::Release); + drop(chain); + + // GROUP-COMMIT PHASE — block until an fsync (ours or a concurrent emitter's) covers + // this seq. Only after this is the record a custody record. + self.wait_durable(seq)?; + } else { + // Memory-only: nothing durable to wait for. + chain.last_seq = seq; + chain.prev_hash = record_hash; + drop(chain); } - // Committed: advance the chain head. - chain.last_seq = seq; - chain.prev_hash = record_hash; - - // Persist the committed head seq for tail-truncation detection (file-backed only). Done under - // the chain lock so the anchor advances monotonically with the head; best-effort — the record - // is already durable and the log was written first, so a failed/lagging anchor never lies. - if let Some(path) = &self.log_path { - if let Err(e) = write_head_anchor(path, seq) { - tracing::error!("AUDIT head-anchor write failed (seq {seq}): {e}"); - } + // Dev-only stdout echo, OFF the chain lock (S52, council S51 red-team F4): a blocked/slow + // stdout (full pipe) must never serialize every emit behind it. Echoed only for records + // that actually committed — an echo of a failed emit would misreport the chain. + if self.echo_stdout { + println!("[AUDIT] {}", line); } - drop(chain); - // Store in the in-memory ring buffer (best-effort; the durable record is the source of truth). + // Store in the in-memory ring buffer (best-effort; the durable record is the source of + // truth). Under concurrency the ring's arrival order may differ slightly from seq order — + // it is an observability projection, never the chain. if let Ok(mut buffer) = self.memory_buffer.write() { if buffer.len() >= MAX_MEMORY_EVENTS { buffer.pop_front(); @@ -714,6 +1295,168 @@ impl AuditLog { Ok(()) } + /// Lock the flush state, RECOVERING from a panic-poisoned mutex (council S51 guardian F3): + /// `FlushState` is three plain fields, each written in a single statement, so a panicked + /// holder cannot leave it structurally invalid — refusing to recover would instead turn one + /// panic into a permanent `AuditError::Lock` for every future custody emit (an unbounded + /// outage, worse than fail-closed). + fn lock_flush<'a>(flush: &'a Mutex) -> std::sync::MutexGuard<'a, FlushState> { + flush + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + } + + /// Refuse if the durable log is poisoned (see [`FlushState::poisoned`]). `Ok` on memory-only + /// logs (no durability to fail). + fn check_not_poisoned(&self) -> Result<(), AuditError> { + if let Some((flush, _)) = &self.flush { + let fs = Self::lock_flush(flush); + if let Some(why) = &fs.poisoned { + return Err(AuditError::Io(format!( + "audit log poisoned by an earlier durability failure (fail-closed; a restart \ + re-verifies the durable prefix — a torn tail needs operator attention): {why}" + ))); + } + } + Ok(()) + } + + /// Mark the durable log permanently failed (until restart): every waiter and every future + /// emit gets `Err`. Never called on a memory-only log. Callable while holding the CHAIN lock + /// (guardian F1 — the write-failure arm must poison before releasing it): chain→flush nesting + /// is acyclic because no path acquires `chain` while holding the flush lock. + fn poison(&self, why: String) { + if let Some((flush, wakeup)) = &self.flush { + let mut fs = Self::lock_flush(flush); + if fs.poisoned.is_none() { + fs.poisoned = Some(why); + } + wakeup.notify_all(); + } + } + + /// Block until `seq` is durably on disk (group commit, S51): serve from a completed fsync, + /// wait out one in flight, or become the flusher. The flusher reads the cover point + /// (`written_seq` — every record whose bytes reached the OS), fsyncs WITHOUT holding the chain + /// lock (appends continue meanwhile), then publishes `durable_seq = cover` and wakes everyone; + /// the head anchor advances to `cover` (durable seqs only — the anchor must never over-claim). + /// An fsync failure poisons the log (see [`FlushState::poisoned`]). + fn wait_durable(&self, seq: u64) -> Result<(), AuditError> { + let Some((flush, wakeup)) = &self.flush else { + // Unreachable for file-backed logs (constructors pair writer+flush); nothing to wait + // for otherwise. + return Ok(()); + }; + let mut fs = Self::lock_flush(flush); + loop { + if let Some(why) = &fs.poisoned { + return Err(AuditError::Io(format!( + "audit record durability unknown — log poisoned (fail-closed): {why}" + ))); + } + if fs.durable_seq >= seq { + return Ok(()); + } + if fs.flushing { + // An fsync is in flight; it may not cover us (we may have appended after its + // cover point was read) — wait for its completion and re-check. Recover a + // panic-poisoned wait the same way lock_flush does (see its doc). + fs = wakeup + .wait(fs) + .unwrap_or_else(std::sync::PoisonError::into_inner); + continue; + } + // Become the flusher for everything appended so far. The guard clears `flushing` and + // poisons on UNWIND (guardian F3): if anything in the flusher section panicked with + // `flushing` stuck true, every later waiter would block forever with nothing left to + // notify them — the guard converts that into the ordinary poisoned-log refusal. + fs.flushing = true; + drop(fs); + struct FlusherGuard<'a> { + log: &'a AuditLog, + armed: bool, + } + impl Drop for FlusherGuard<'_> { + fn drop(&mut self) { + if self.armed { + if let Some((flush, wakeup)) = &self.log.flush { + let mut fs = AuditLog::lock_flush(flush); + fs.flushing = false; + if fs.poisoned.is_none() { + fs.poisoned = + Some("flusher panicked mid-flush (fail-closed)".to_string()); + } + wakeup.notify_all(); + } + } + } + } + let mut guard = FlusherGuard { + log: self, + armed: true, + }; + // Cover point BEFORE the fsync: all seqs ≤ written_seq have their bytes in the OS + // (Release-stored under the chain lock after the BufWriter flush), so sync_all + // durably commits every one of them. Our own seq is ≤ cover by construction. + let cover = self.written_seq.load(Ordering::Acquire); + // fsync the CLONED fd so appenders keep the writer mutex (see `sync_handle` — the + // measured convoy fix); fall back to fsync-under-the-writer-lock if the clone failed. + let sync_res = match &self.sync_handle { + Some(h) => h.sync_all().map_err(|e| e.to_string()), + None => match &self.writer { + Some(writer) => match writer.lock() { + Ok(w) => w.get_ref().sync_all().map_err(|e| e.to_string()), + Err(_) => Err("writer lock poisoned".to_string()), + }, + None => Err("no writer to fsync (invariant violation)".to_string()), + }, + }; + // Loud logging OUTSIDE the flush lock (a panicking tracing subscriber must not poison + // it — guardian F3). + if let Err(e) = &sync_res { + tracing::error!("AUDIT sync_all failed (covering seq {cover}): {e}"); + } + { + let mut fs = Self::lock_flush(flush); + fs.flushing = false; + guard.armed = false; // completed normally — the guard must not poison + match &sync_res { + Ok(()) => { + fs.durable_seq = fs.durable_seq.max(cover); + wakeup.notify_all(); + } + Err(e) => { + fs.poisoned = Some(format!("fsync failed covering seq {cover}: {e}")); + wakeup.notify_all(); + return Err(AuditError::Io(format!( + "audit record durability unknown — fsync failed (log poisoned, \ + fail-closed): {e}" + ))); + } + } + } + // Tail-truncation anchor for the DURABLE cover — OFF the flush lock (it must never + // hold up the waiters just woken above; the first S51 cut anchored under the flush + // lock and serialized every group-commit cycle behind it). Guarded-monotone via its + // own mutex (an overlapping later flusher cannot regress it); best-effort — a lagging + // anchor under-claims, never lies. + if let Some(path) = &self.log_path { + if let Ok(mut anchored) = self.anchored_seq.lock() { + if cover > *anchored { + match write_head_anchor(path, cover) { + Ok(()) => *anchored = cover, + Err(e) => { + tracing::error!("AUDIT head-anchor write failed (seq {cover}): {e}") + } + } + } + } + } + // The flusher's own record is covered by construction (seq ≤ written_seq ≤ cover). + return Ok(()); + } + } + /// Walk the on-disk log and VERIFY the hash-chain + signatures end to end. Returns the number of /// records verified, or an error naming the first break (bad seq, broken link, wrong hash, or a /// signature that does not verify under `verifying_key`). This is the tamper-evidence check. @@ -748,9 +1491,8 @@ impl AuditLog { rec.seq )); } - let event_json = serde_json::to_string(&rec.event) + let computed = recompute_record_hash(&rec, &expected_prev) .map_err(|e| format!("seq {}: re-serialize event: {e}", rec.seq))?; - let computed = compute_record_hash(rec.seq, &expected_prev, event_json.as_bytes()); let claimed = hex::decode(&rec.record_hash) .map_err(|e| format!("seq {}: bad record_hash hex: {e}", rec.seq))?; if claimed.as_slice() != computed.as_slice() { @@ -834,6 +1576,110 @@ impl AuditLog { }) } + /// Sign the exact ordered record SET of a receipt with this log's key (base64 ed25519 over + /// [`mandate_receipt_binding_message`]). The self-contained binding a verifier re-checks to + /// detect any holder-side add/drop/reorder. `None` for an unsigned log. + fn sign_receipt_set( + &self, + scope: &MandateReceiptScope, + records: &[ChainedRecord], + ) -> Option { + let signer = self.signer.as_ref()?; + Some( + BASE64.encode( + signer + .sign(&mandate_receipt_binding_message(scope, records)) + .to_bytes(), + ), + ) + } + + /// Export the durable chain as a PORTABLE [`MandateReceipt`] a third party can verify off-box + /// with [`verify_mandate_receipt`] and NO runtime. `None` for a memory-only or unsigned log + /// (nothing durable + signed to hand out). + pub fn export_mandate_receipt(&self) -> Option { + self.export_mandate_receipt_range(1, u64::MAX) + } + + /// As [`export_mandate_receipt`](Self::export_mandate_receipt), scoped to a `seq` range so a + /// receipt can carry just ONE mandate + the actions taken under it (`[from_seq, to_seq]`, + /// inclusive) rather than the whole history — the shape an auditor is handed per delegation. + pub fn export_mandate_receipt_range( + &self, + from_seq: u64, + to_seq: u64, + ) -> Option { + let path = self.log_path.as_ref()?; + let signer_public_key_hex = self.verifying_key_hex()?; // unsigned ⇒ no verifiable receipt + let file = File::open(path).ok()?; + let reader = BufReader::new(file); + let mut records = Vec::new(); + for line in reader.lines() { + let line = line.ok()?; + if line.trim().is_empty() { + continue; + } + let record: ChainedRecord = serde_json::from_str(&line).ok()?; + if record.seq >= from_seq && record.seq <= to_seq { + records.push(record); + } + } + if records.is_empty() { + return None; + } + let scope = MandateReceiptScope::Contiguous; + let set_binding = self.sign_receipt_set(&scope, &records); + Some(MandateReceipt { + schema: MANDATE_RECEIPT_SCHEMA.to_string(), + scope, + signer_public_key_hex, + records, + set_binding, + }) + } + + /// Export a PER-MANDATE receipt: EVERY durable record bound to one capability `token_id` — the + /// grant (the mandate) plus every use / revoke under it — regardless of where they sit in the + /// interleaved chain. This is the delegation-shaped artifact you hand an auditor: "here is the + /// authorization, and here are the actions taken under it." `None` for a memory-only/unsigned + /// log or a `token_id` with no records. Verified with [`MandateReceiptScope::Capability`]. + /// + /// COMPLETENESS is bounded (see that scope's docs): the `set_binding` signature makes the record + /// set tamper-evident against any HOLDER in transit, but a compromised key-holding issuer could + /// still sign a selective set. Unlike a `Contiguous` receipt, this does NOT prove the issuer + /// omitted no action at export — the bundle carries no such attestation, and none is implied. + pub fn export_mandate_receipt_for_capability(&self, token_id: &str) -> Option { + let path = self.log_path.as_ref()?; + let signer_public_key_hex = self.verifying_key_hex()?; + let file = File::open(path).ok()?; + let reader = BufReader::new(file); + let mut records = Vec::new(); + for line in reader.lines() { + let line = line.ok()?; + if line.trim().is_empty() { + continue; + } + let record: ChainedRecord = serde_json::from_str(&line).ok()?; + if record.event.capability_token_id() == Some(token_id) { + records.push(record); + } + } + if records.is_empty() { + return None; + } + let scope = MandateReceiptScope::Capability { + token_id: token_id.to_string(), + }; + let set_binding = self.sign_receipt_set(&scope, &records); + Some(MandateReceipt { + schema: MANDATE_RECEIPT_SCHEMA.to_string(), + scope, + signer_public_key_hex, + records, + set_binding, + }) + } + /// Best-effort emit for NON-custody events (capsule lifecycle, capability use, etc.): logs /// loudly at `error!` on failure but never propagates. This is the "fail-loud but don't block" /// half of the split — custody callers ([`content_open`](Self::content_open) and direct @@ -946,6 +1792,9 @@ impl AuditLog { resource: resource.to_string(), action: action.to_string(), expiry, + // The legacy best-effort helper predates the liability binding; the durable mandate + // mint (`grant_durable`) is the path that records the responsible entity. + responsible_entity: None, }); } @@ -966,6 +1815,22 @@ impl AuditLog { resource: &ResourceId, action: Action, success: bool, + ) { + self.capability_use_with_rail_ref(token_id, capsule_id, resource, action, success, None); + } + + /// Emit a `CapabilityUse` carrying the rail reference for an act that settled on an external + /// rail (Sprint 34 — a `runtime.pay` DRM buy's tx hash + `operative:tokenId`). Passing `None` + /// is exactly [`capability_use`](Self::capability_use); the field is omitted from the signed + /// preimage, so a rail-less use stays byte-identical to a pre-S34 record. + pub fn capability_use_with_rail_ref( + &self, + token_id: &TokenId, + capsule_id: &str, + resource: &ResourceId, + action: Action, + success: bool, + rail_ref: Option, ) { self.emit_best_effort(AuditEvent::CapabilityUse { timestamp: SecureTimestamp::now(), @@ -974,6 +1839,7 @@ impl AuditLog { resource: resource.to_string(), action: action.to_string(), success, + rail_ref, }); } @@ -1170,6 +2036,43 @@ impl AuditLog { self.recent_events(limit) } + /// Whether the audit history records that `principal_id` SUCCESSFULLY OPENED `content_id` — a + /// `ContentOpen` with matching `principal_id` and `decision == "opened"`. PRINCIPAL-SCOPED: it + /// answers "did THIS principal access X", never "did anyone" — so it cannot be a cross-principal + /// existence oracle. (`ContentFetch` is deliberately NOT counted: it carries no principal, so it + /// cannot be attributed.) A state-dependent, side-effect-free read whose answer varies with what + /// the principal actually did. Streams the durable log and EARLY-RETURNS on the first match (O(1) + /// memory); falls back to the in-memory buffer for an unsigned/memory-only log. A `false` over a + /// file-backed log is authoritative for the DURABLE history. + pub fn principal_opened_content(&self, principal_id: &str, content_id: &str) -> bool { + fn matches(event: &AuditEvent, principal: &str, id: &str) -> bool { + matches!( + event, + AuditEvent::ContentOpen { content_id, principal_id, decision, .. } + if content_id == id && principal_id == principal && decision == "opened" + ) + } + if let Some(path) = &self.log_path { + if let Ok(file) = File::open(path) { + for line in BufReader::new(file).lines().map_while(Result::ok) { + if line.trim().is_empty() { + continue; + } + if let Ok(rec) = serde_json::from_str::(&line) { + if matches(&rec.event, principal_id, content_id) { + return true; + } + } + } + return false; + } + } + self.memory_buffer + .read() + .map(|buf| buf.iter().any(|e| matches(e, principal_id, content_id))) + .unwrap_or(false) + } + /// Get total event count in memory buffer pub fn event_count(&self) -> usize { if let Ok(buffer) = self.memory_buffer.read() { @@ -1217,6 +2120,24 @@ impl AuditEvent { AuditEvent::Custom { .. } => "custom", } } + + /// The capability `token_id` this event pertains to — the identifier that binds a mandate + /// (`CapabilityGrant`) to the actions taken under it (`CapabilityUse`) and its revocation + /// (`CapabilityRevoke`). `None` for events that are not scoped to a single capability token. + /// Used to filter the chain into a per-mandate receipt. + pub fn capability_token_id(&self) -> Option<&str> { + match self { + AuditEvent::CapabilityGrant { token_id, .. } + | AuditEvent::CapabilityRevoke { token_id, .. } + | AuditEvent::CapabilityUse { token_id, .. } => Some(token_id.as_str()), + _ => None, + } + } + + /// True iff this event is the authorization (the mandate itself) — a `CapabilityGrant`. + pub fn is_capability_grant(&self) -> bool { + matches!(self, AuditEvent::CapabilityGrant { .. }) + } } impl Default for AuditLog { @@ -1328,10 +2249,19 @@ fn load_or_create_signer(log_path: &Path) -> std::io::Result { let signing_key = SigningKey::generate(&mut rand::thread_rng()); write_private(&key_path, &signing_key.to_bytes())?; let pub_path = sibling(log_path, "pubkey"); - let _ = std::fs::write( + // Publishing the verifying key is best-effort (the signing key is already durably held and + // the chain stays verifiable via an out-of-band key copy) — but a silent failure would leave + // verifiers with no key file and no clue, so say it loudly. + if let Err(e) = std::fs::write( &pub_path, hex::encode(signing_key.verifying_key().to_bytes()), - ); + ) { + tracing::error!( + "audit verifying key could not be published to {}: {e} — verifiers have no key file \ + until it is written out of band", + pub_path.display() + ); + } Ok(signing_key) } @@ -1351,19 +2281,39 @@ fn load_or_create_signer(log_path: &Path) -> std::io::Result { fn write_head_anchor(log_path: &Path, committed_seq: u64) -> std::io::Result<()> { let anchor_path = sibling(log_path, "head-anchor"); let tmp_path = sibling(log_path, "head-anchor.tmp"); + // DELIBERATELY NOT fsynced (measured, S51 council fold): a single-threaded emitter is its own + // flusher, so an anchor fsync would DOUBLE its per-record durable cost (~950 µs → ~1.7 ms + // measured on the S51 box — the first fold cut did exactly that and the bench rejected it). + // Crash safety without it (guardian F4's brick scenario): the payload is a ≤20-byte decimal in + // ONE sector, so a crash leaves the renamed anchor either COMPLETE or (on filesystems with no + // rename-data-ordering heuristic) EMPTY — never partial garbage — and `read_head_anchor` + // treats EMPTY as absent: the floor is skipped for that one open, loudly, and the next flush + // rewrites it. A stale-but-complete older anchor is the ordinary best-effort lag (never lies + // high — see the caller's ordering). std::fs::write(&tmp_path, committed_seq.to_string())?; std::fs::rename(&tmp_path, &anchor_path) } /// Read the committed chain-head sequence from `.head-anchor`. /// -/// - `Ok(None)` — no anchor (a pre-anchor log or a brand-new file); the truncation check is skipped. +/// - `Ok(None)` — no anchor (a pre-anchor log or a brand-new file), OR an EMPTY anchor file (the +/// pre-S51 non-fsynced writer could land one across a crash — defense in depth, warned loudly; +/// treating it as absent only SKIPS the truncation check, never invents a floor). The check is +/// skipped. /// - `Ok(Some(seq))` — a well-formed anchor (the LOWER bound on how many records must be present). -/// - `Err` — the anchor exists but is unparseable; fail-CLOSED, since the atomic rename rules out a -/// torn write, so a corrupt anchor in durable mode is genuinely suspicious. +/// - `Err` — the anchor has non-empty garbage; fail-CLOSED: the single-sector atomic write means a +/// crash yields a complete or EMPTY anchor (handled above), never partial garbage — so non-empty +/// garbage in durable mode is genuinely suspicious. fn read_head_anchor(log_path: &Path) -> std::io::Result> { let anchor_path = sibling(log_path, "head-anchor"); match std::fs::read_to_string(&anchor_path) { + Ok(s) if s.trim().is_empty() => { + tracing::warn!( + "audit head-anchor at {anchor_path:?} is EMPTY (a pre-S51 crash artifact) — \ + treating as absent; the tail-truncation floor is unavailable for this open" + ); + Ok(None) + } Ok(s) => s.trim().parse::().map(Some).map_err(|e| { std::io::Error::new( std::io::ErrorKind::InvalidData, @@ -1375,6 +2325,65 @@ fn read_head_anchor(log_path: &Path) -> std::io::Result> { } } +/// Recover a TORN TAIL at open (council S51 guardian F2 / red-team F1): if the log does not end +/// with `\n`, its trailing partial line is quarantined to `.torn-tail` and the log truncated +/// back to the last newline, so both open modes resume from an intact prefix instead of (verified) +/// refusing a healthy log or (plain) appending onto the fragment and merging two records into one +/// garbage line. +/// +/// WHY THIS IS SAFE, precisely: +/// - A record is acknowledged (`emit` → `Ok`) only after a successful fsync of its FULL +/// `line\n` write — so a file whose last bytes lack the terminating `\n` PROVES the fragment +/// was never acknowledged (a crash tore it mid-writeback, or its write failed and poisoned the +/// log). Removing it can never remove an acknowledged custody record. +/// - It grants a tamperer nothing: beyond the head-anchor floor, a clean cut at a line boundary +/// is already undetectable (the anchor is the only lower bound), so laundering a cut as a +/// "torn tail" adds no power; at or below the floor, the anchor check still refuses. +/// - The fragment is PRESERVED (appended to the sidecar with a marker line), not destroyed — +/// append-only in spirit: nothing acknowledged is ever dropped, and even the torn bytes remain +/// inspectable. +/// +/// A torn/corrupt line in the MIDDLE of the file (terminated by `\n`) is NOT recovered — that is +/// indistinguishable from tamper and stays fail-closed at the verified open. +fn quarantine_torn_tail(path: &Path) -> std::io::Result<()> { + let bytes = match std::fs::read(path) { + Ok(b) => b, + Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(()), + Err(e) => return Err(e), + }; + if bytes.is_empty() || bytes.ends_with(b"\n") { + return Ok(()); + } + let keep = bytes.iter().rposition(|b| *b == b'\n').map_or(0, |i| i + 1); + let fragment = &bytes[keep..]; + let sidecar = sibling(path, "torn-tail"); + { + let mut f = OpenOptions::new() + .create(true) + .append(true) + .open(&sidecar)?; + writeln!( + f, + "--- torn tail quarantined ({} bytes) ---", + fragment.len() + )?; + f.write_all(fragment)?; + writeln!(f)?; + f.sync_all()?; + } + // Truncate AFTER the fragment is durably in the sidecar — a crash between the two leaves the + // fragment in both places (harmless duplicate), never in neither. + let f = OpenOptions::new().write(true).open(path)?; + f.set_len(keep as u64)?; + f.sync_all()?; + tracing::warn!( + "audit log at {path:?} had a torn (never-acknowledged) trailing fragment of {} bytes — \ + quarantined to {sidecar:?} and resumed from the intact prefix", + fragment.len() + ); + Ok(()) +} + /// Build a sibling path `.` next to the audit log. fn sibling(log_path: &Path, suffix: &str) -> PathBuf { let mut name = log_path @@ -1462,6 +2471,359 @@ mod tests { VerifyingKey::from_bytes(&bytes).unwrap() } + // ---- Portable mandate receipt (Sprint 1, Item 2) ---------------------------------------- + // Emit a small chain to a signed, file-backed log and return an exported receipt. + fn emit_and_export_receipt() -> (tempfile::TempDir, MandateReceipt) { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("audit.log"); + let log = AuditLog::with_file(&path).unwrap(); + log.emit(AuditEvent::RuntimeStart { + timestamp: SecureTimestamp::now(), + version: "mandate".to_string(), + }) + .expect("emit mandate"); + log.content_open( + "sess-1", + "person:local:alice", + "elastos://content/abc", + "view", + "opened", + "chain-provider", + None, + ) + .expect("emit action"); + let receipt = log + .export_mandate_receipt() + .expect("a signed file-backed log exports a receipt"); + (dir, receipt) + } + + #[test] + fn mandate_receipt_verifies_standalone_over_the_wire() { + let (_dir, receipt) = emit_and_export_receipt(); + let pin = receipt.signer_public_key_hex.clone(); + // Round-trip through JSON to prove it is a PORTABLE document, then verify with ONLY the + // receipt — no AuditLog, no disk, no runtime. This is the "an auditor can check it" primitive. + let wire = serde_json::to_string(&receipt).unwrap(); + let received: MandateReceipt = serde_json::from_str(&wire).unwrap(); + + // Structural check (no pin): sound, but NOT authenticity. + let structural = verify_mandate_receipt(&received, None); + assert!( + structural.structurally_valid, + "clean receipt is structurally valid: {structural:?}" + ); + assert!(!structural.authenticated, "no pin ⇒ not authenticated"); + assert_eq!(structural.signer_matches_expected, None); + assert!(structural.hashes_ok && structural.signatures_ok && structural.chain_linkage_ok); + assert_eq!(structural.records, 2); + assert!( + structural.starts_at_genesis, + "the export begins at seq 1 / genesis" + ); + + // Pinned to the real signer: AUTHENTIC (the bit an auditor acts on). + let authentic = verify_mandate_receipt(&received, Some(&pin)); + assert!( + authentic.authenticated, + "pinned to the true signer ⇒ authenticated: {authentic:?}" + ); + assert_eq!(authentic.signer_matches_expected, Some(true)); + } + + /// The security property both reviewers demanded: a receipt an ATTACKER self-signed is + /// structurally valid under its own key, but is NEVER `authenticated` without an out-of-band pin, + /// and fails authentication when pinned to the real (different) signer. + #[test] + fn mandate_receipt_requires_signer_pinning_for_authenticity() { + let (_dir, real) = emit_and_export_receipt(); + let real_signer = real.signer_public_key_hex.clone(); + + // Attacker fabricates their OWN chain, signs it with their OWN key, and ships a receipt. + let dir = tempfile::tempdir().unwrap(); + let log = AuditLog::with_file(dir.path().join("evil.log")).unwrap(); + log.emit(AuditEvent::RuntimeStart { + timestamp: SecureTimestamp::now(), + version: "fabricated".to_string(), + }) + .unwrap(); + let forged = log.export_mandate_receipt().unwrap(); + + // It is structurally valid under its OWN key... + let structural = verify_mandate_receipt(&forged, None); + assert!(structural.structurally_valid); + assert!( + !structural.authenticated, + "self-signed is not authentic without a pin" + ); + + // ...but pinning to the REAL runtime's signer exposes it: not the expected signer. + let against_real = verify_mandate_receipt(&forged, Some(&real_signer)); + assert!( + !against_real.authenticated, + "forged receipt must fail against the pinned real signer" + ); + assert_eq!(against_real.signer_matches_expected, Some(false)); + } + + #[test] + fn mandate_receipt_detects_event_tamper() { + let (_dir, mut receipt) = emit_and_export_receipt(); + // Edit a recorded event AFTER export: the record_hash no longer recomputes. + if let AuditEvent::RuntimeStart { version, .. } = &mut receipt.records[0].event { + *version = "tampered".to_string(); + } else { + panic!("expected RuntimeStart at records[0]"); + } + let verdict = verify_mandate_receipt(&receipt, None); + assert!(!verdict.structurally_valid, "an edited event must fail"); + assert!( + !verdict.hashes_ok, + "record_hash must not recompute after an edit" + ); + } + + #[test] + fn mandate_receipt_detects_signature_forgery() { + let (_dir, mut receipt) = emit_and_export_receipt(); + // Corrupt a signature: a valid base64 blob that is not the real signature. + receipt.records[1].sig = BASE64.encode([0u8; 64]); + let verdict = verify_mandate_receipt(&receipt, None); + assert!(!verdict.structurally_valid); + assert!(!verdict.signatures_ok, "a forged signature must not verify"); + } + + #[test] + fn mandate_receipt_detects_dropped_record() { + // Emit three records so we can drop the MIDDLE one and break contiguity. + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("audit.log"); + let log = AuditLog::with_file(&path).unwrap(); + for v in ["a", "b", "c"] { + log.emit(AuditEvent::RuntimeStart { + timestamp: SecureTimestamp::now(), + version: v.to_string(), + }) + .unwrap(); + } + let mut three = log.export_mandate_receipt().unwrap(); + assert_eq!(three.records.len(), 3); + three.records.remove(1); // drop the middle record + let verdict = verify_mandate_receipt(&three, None); + assert!(!verdict.structurally_valid); + assert!( + !verdict.chain_linkage_ok, + "a dropped record must break linkage" + ); + } + + #[test] + fn mandate_receipt_rejects_a_wrong_signer_key() { + let (_dir, mut receipt) = emit_and_export_receipt(); + // A different (valid) ed25519 key — the records were not signed under it. + let other: [u8; 32] = [ + 0xd7, 0x5a, 0x98, 0x01, 0x82, 0xb1, 0x0a, 0xb7, 0xd5, 0x4b, 0xfe, 0xd3, 0xc9, 0x64, + 0x07, 0x3a, 0x0e, 0xe1, 0x72, 0xf3, 0xda, 0xa6, 0x23, 0x25, 0xaf, 0x02, 0x1a, 0x68, + 0xf7, 0x07, 0x51, 0x1a, + ]; + receipt.signer_public_key_hex = hex::encode(other); + let verdict = verify_mandate_receipt(&receipt, None); + assert!(!verdict.structurally_valid); + assert!( + !verdict.signatures_ok, + "records must not verify under a foreign key" + ); + } + + #[test] + fn mandate_receipt_rejects_a_wrong_schema() { + let (_dir, mut receipt) = emit_and_export_receipt(); + receipt.schema = "elastos.evil/v9".to_string(); + let verdict = verify_mandate_receipt(&receipt, None); + assert!(!verdict.structurally_valid && !verdict.authenticated); + assert!( + verdict.error.is_some(), + "wrong schema must fail closed with a reason" + ); + } + + #[test] + fn mandate_receipt_is_none_for_a_memory_only_log() { + // A memory-only log has no durable, signed chain to hand out — no receipt. + assert!(AuditLog::new().export_mandate_receipt().is_none()); + // And an empty receipt fails closed. + let empty = MandateReceipt { + schema: MANDATE_RECEIPT_SCHEMA.to_string(), + scope: MandateReceiptScope::Contiguous, + signer_public_key_hex: String::new(), + records: vec![], + set_binding: None, + }; + let verdict = verify_mandate_receipt(&empty, None); + assert!(!verdict.structurally_valid && !verdict.authenticated); + } + + // Emit a mandate (grant) + two uses under it, INTERLEAVED with unrelated events, then export the + // per-capability receipt. Returns (dir, receipt, signer_hex, token_id). + fn emit_and_export_capability_receipt() -> (tempfile::TempDir, MandateReceipt, String, String) { + use crate::capability::token::{Action, ResourceId, TokenId}; + let dir = tempfile::tempdir().unwrap(); + let log = AuditLog::with_file(dir.path().join("audit.log")).unwrap(); + let token = TokenId::new(); + let token_id = token.to_string(); + let vendor = ResourceId::new("elastos://pay/vendor"); + // Unrelated noise before + between the mandate's records (interleaving is the whole point). + log.emit(AuditEvent::RuntimeStart { + timestamp: SecureTimestamp::now(), + version: "noise".to_string(), + }) + .unwrap(); + log.capability_grant(&token, "vm-agent", &vendor, Action::Write, None); + log.emit(AuditEvent::RuntimeStart { + timestamp: SecureTimestamp::now(), + version: "noise-2".to_string(), + }) + .unwrap(); + log.capability_use(&token, "vm-agent", &vendor, Action::Write, true); + log.capability_use(&token, "vm-agent", &vendor, Action::Write, true); + let signer = log.verifying_key_hex().unwrap(); + let receipt = log + .export_mandate_receipt_for_capability(&token_id) + .expect("per-capability receipt"); + (dir, receipt, signer, token_id) + } + + #[test] + fn per_capability_receipt_binds_the_mandate_and_its_actions_and_authenticates() { + let (_dir, receipt, signer, _token) = emit_and_export_capability_receipt(); + // Exactly the grant + its two uses — the interleaved noise is excluded. + assert_eq!(receipt.records.len(), 3, "grant + 2 uses, noise excluded"); + assert!(matches!( + receipt.scope, + MandateReceiptScope::Capability { .. } + )); + // Round-trips as a portable document and authenticates when pinned to the real signer. + let wire = serde_json::to_string(&receipt).unwrap(); + let received: MandateReceipt = serde_json::from_str(&wire).unwrap(); + let verdict = verify_mandate_receipt(&received, Some(&signer)); + assert!( + verdict.structurally_valid, + "scoped receipt is sound: {verdict:?}" + ); + assert!( + verdict.scope_ok, + "all records bound to the token + exactly one grant" + ); + assert!( + verdict.set_binding_ok, + "issuer's set-binding signature verifies" + ); + assert!( + verdict.authenticated, + "pinned to the true signer ⇒ authenticated" + ); + // `starts_at_genesis` is N/A here: the grant sits mid-chain after noise, so it is false and + // MUST NOT be read as a completeness/suspicion signal for a Capability receipt. + assert!( + !verdict.starts_at_genesis, + "grant is mid-chain ⇒ genesis anchor N/A" + ); + } + + #[test] + fn per_capability_set_binding_detects_a_keyless_dropped_use() { + // The completeness attack both reviewers flagged: a HOLDER (no signing key) trims an + // inconvenient use from the JSON. Every remaining record still hashes, signs, and is bound to + // the token (scope_ok stays true), so ONLY the issuer's set-binding signature can catch it. + let (_dir, mut receipt, signer, _token) = emit_and_export_capability_receipt(); + // Drop one USE (keep the grant): the filtered scope rule is still satisfied by what remains. + let victim = receipt + .records + .iter() + .position(|r| !r.event.is_capability_grant()) + .expect("a use to drop"); + receipt.records.remove(victim); + let verdict = verify_mandate_receipt(&receipt, Some(&signer)); + assert!( + verdict.scope_ok, + "the trimmed set still passes the filter rule — that is the trap" + ); + assert!( + !verdict.set_binding_ok, + "the issuer's set binding no longer matches the trimmed set" + ); + assert!( + !verdict.structurally_valid, + "a holder-trimmed set must not verify" + ); + assert!(!verdict.authenticated, "and it must not authenticate"); + } + + #[test] + fn per_capability_receipt_rejects_a_duplicated_record() { + // Duplicate a signed use to inflate/misrepresent activity. Strict-seq breaks scope_ok and the + // changed set breaks the binding — belt and suspenders. + let (_dir, mut receipt, signer, _token) = emit_and_export_capability_receipt(); + let clone = receipt.records.last().unwrap().clone(); + receipt.records.push(clone); + let verdict = verify_mandate_receipt(&receipt, Some(&signer)); + assert!(!verdict.scope_ok, "duplicate seq breaks strict ordering"); + assert!( + !verdict.set_binding_ok, + "a duplicated record changes the bound set" + ); + assert!(!verdict.structurally_valid); + } + + #[test] + fn per_capability_receipt_rejects_a_smuggled_foreign_record() { + let (_dir, mut receipt, signer, _token) = emit_and_export_capability_receipt(); + // Splice in a record from a DIFFERENT delegation. It is individually AUTHENTIC (really + // signed), but it is NOT bound to this mandate's token_id → scope_ok must fail. + let dir2 = tempfile::tempdir().unwrap(); + let log2 = AuditLog::with_file(dir2.path().join("other.log")).unwrap(); + use crate::capability::token::{Action, ResourceId, TokenId}; + log2.capability_use( + &TokenId::new(), + "vm-agent", + &ResourceId::new("elastos://pay/vendor"), + Action::Write, + true, + ); + // Re-sign it under THE SAME signer so signatures still verify (only the token differs). + // (Simplest: pull a real foreign record from log2's file.) + let other_line = std::fs::read_to_string(dir2.path().join("other.log")).unwrap(); + let foreign: ChainedRecord = + serde_json::from_str(other_line.lines().next().unwrap()).unwrap(); + receipt.records.push(foreign); + // Verify against the receipt's OWN signer (structural), not the cross-log signer — the point + // is the SCOPE check, which must reject the foreign token regardless of signature origin. + let verdict = verify_mandate_receipt(&receipt, Some(&signer)); + assert!( + !verdict.scope_ok, + "a foreign-token record must break scope_ok" + ); + assert!( + !verdict.structurally_valid, + "scope failure ⇒ not structurally valid" + ); + let _ = signer; + } + + #[test] + fn per_capability_receipt_requires_the_grant_to_be_present() { + let (_dir, mut receipt, signer, _token) = emit_and_export_capability_receipt(); + // Drop the mandate itself (the grant), leaving only uses: a receipt of actions with no + // authorization must not pass its scope rule (exactly one grant required). + receipt.records.retain(|r| !r.event.is_capability_grant()); + assert!(!receipt.records.is_empty()); + let verdict = verify_mandate_receipt(&receipt, Some(&signer)); + assert!( + !verdict.scope_ok, + "no grant ⇒ scope_ok false (actions without a mandate)" + ); + } + #[test] fn emit_chains_seq_and_a_clean_log_verifies() { let dir = tempfile::tempdir().unwrap(); @@ -1893,6 +3255,211 @@ mod tests { ); } + /// GROUP-COMMIT RATCHET (S51): concurrent emitters on one file-backed log all succeed, and the + /// resulting chain is PERFECT — contiguous seqs, every hash link and signature verifying end to + /// end, and the head anchor at the full count. This is the whole safety claim of the group + /// commit in one test: coalescing fsyncs must not reorder, drop, interleave, or half-commit a + /// single record. (The THROUGHPUT claim is measured, not asserted: `benches/audit_emit.rs`.) + #[test] + fn concurrent_emits_group_commit_and_the_chain_stays_perfect() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("audit.log"); + let log = std::sync::Arc::new(AuditLog::with_file(&path).unwrap()); + + const THREADS: usize = 8; + const PER_THREAD: usize = 25; + let handles: Vec<_> = (0..THREADS) + .map(|t| { + let log = log.clone(); + std::thread::spawn(move || { + for i in 0..PER_THREAD { + log.emit(AuditEvent::RuntimeStart { + timestamp: SecureTimestamp::now(), + version: format!("t{t}-{i}"), + }) + .expect("a concurrent emit must durably commit"); + } + }) + }) + .collect(); + for h in handles { + h.join().unwrap(); + } + + let total = (THREADS * PER_THREAD) as u64; + let vk = log.signer.as_ref().map(|s| s.verifying_key()); + assert_eq!( + log.verify_chain(vk.as_ref()).expect("chain verifies clean"), + total, + "every concurrent emit is on the chain exactly once, in order, signed" + ); + assert_eq!( + super::read_head_anchor(&path).unwrap(), + Some(total), + "the head anchor reached the full durable count" + ); + // And the log re-opens fail-closed-verified — the on-disk artifact is coherent. + drop(log); + drop(AuditLog::with_file_verified(&path).unwrap()); + } + + /// TORN-TAIL RECOVERY RATCHET (S51 council fold — guardian F2 / red-team F1): a crash can tear + /// the final (never-acknowledged — its fsync never completed, so its emit never returned Ok) + /// line mid-writeback. The open must QUARANTINE that fragment and resume from the intact + /// durable prefix — never refuse the healthy log (verified mode) and never append onto the + /// fragment merging two records into garbage (plain mode). A corrupt line in the MIDDLE stays + /// fail-closed (tamper — covered by `with_file_verified_resumes_clean_log_and_rejects_tamper`). + #[test] + fn a_torn_tail_is_quarantined_and_the_log_resumes_from_the_durable_prefix() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("audit.log"); + { + let log = AuditLog::with_file(&path).unwrap(); + log.emit(AuditEvent::RuntimeStart { + timestamp: SecureTimestamp::now(), + version: "a".to_string(), + }) + .unwrap(); + log.emit(AuditEvent::RuntimeStart { + timestamp: SecureTimestamp::now(), + version: "b".to_string(), + }) + .unwrap(); + } + // Simulate the crash-torn tail: half a record, NO terminating newline. + { + use std::io::Write as _; + let mut f = std::fs::OpenOptions::new() + .append(true) + .open(&path) + .unwrap(); + f.write_all(br#"{"seq":3,"prev_hash":"dead"#).unwrap(); + } + // The VERIFIED open (the production custody boot path) recovers instead of bricking... + let log = AuditLog::with_file_verified(&path).expect( + "a torn never-acknowledged tail must be quarantined, not refuse the healthy log", + ); + // ...the fragment is preserved in the sidecar... + let sidecar = std::fs::read_to_string(super::sibling(&path, "torn-tail")).unwrap(); + assert!( + sidecar.contains(r#"{"seq":3,"prev_hash":"dead"#), + "the torn bytes are quarantined, not destroyed: {sidecar}" + ); + // ...and the log RESUMES: the next emit is seq 3 and the whole chain verifies. + log.emit(AuditEvent::RuntimeStart { + timestamp: SecureTimestamp::now(), + version: "c".to_string(), + }) + .unwrap(); + let vk = log.signer.as_ref().map(|s| s.verifying_key()); + assert_eq!( + log.verify_chain(vk.as_ref()).expect("chain verifies clean"), + 3, + "resumed exactly at the durable prefix; no gap, no duplicate" + ); + } + + /// SINGLE-OPENER RATCHET (S52, closing the S51 red-team dual-writer residual): a second live + /// opener of the SAME log file is refused fail-closed — two instances would keep independent + /// chain heads, mint the same seqs, and corrupt the on-disk chain (and under the group commit + /// one instance's fsync covers the sibling's uncoordinated bytes). Same flock discipline as + /// the spend meter and payment ledger. Reopen after drop succeeds (the lock dies with the log). + #[cfg(unix)] + #[test] + fn a_second_live_opener_of_the_same_log_is_refused() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("audit.log"); + let first = AuditLog::with_file(&path).unwrap(); + let second = AuditLog::with_file(&path); + match second { + Err(e) => { + assert_eq!(e.kind(), std::io::ErrorKind::WouldBlock); + assert!( + e.to_string().contains("single-opener"), + "names the discipline: {e}" + ); + } + Ok(_) => panic!("a second live opener must be refused (single-opener, fail-closed)"), + } + // The verified open is refused the same way (it routes through with_file). + assert!( + AuditLog::with_file_verified(&path).is_err(), + "verified open also respects the single-opener lock" + ); + drop(first); + // The lock dies with the log — a sequential reopen (restart) succeeds. + drop(AuditLog::with_file(&path).unwrap()); + } + + /// POISON-BEFORE-APPEND RATCHET (S51 council fold — guardian F1 / red-team F2): the + /// authoritative poison check runs UNDER the chain lock, so a poisoned log refuses an emit + /// BEFORE assigning a seq or writing a byte — an emit racing a failing one can never re-derive + /// the failed seq and append behind its half-landed bytes. + #[test] + fn a_poisoned_log_refuses_before_assigning_a_seq_or_writing() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("audit.log"); + let log = AuditLog::with_file(&path).unwrap(); + log.emit(AuditEvent::RuntimeStart { + timestamp: SecureTimestamp::now(), + version: "a".to_string(), + }) + .unwrap(); + let bytes_before = std::fs::metadata(&path).unwrap().len(); + + log.poison("injected durability failure (test)".to_string()); + let res = log.emit(AuditEvent::RuntimeStart { + timestamp: SecureTimestamp::now(), + version: "b".to_string(), + }); + assert!( + matches!(&res, Err(e) if e.to_string().contains("poisoned")), + "a poisoned log refuses: {res:?}" + ); + assert_eq!( + std::fs::metadata(&path).unwrap().len(), + bytes_before, + "the refused emit wrote NOTHING — no seq derived, no bytes appended" + ); + assert_eq!( + log.chain.lock().unwrap().last_seq, + 1, + "the chain head is untouched by the refused emit" + ); + } + + /// POISON RATCHET (S51): after a failed durable write the log refuses EVERY subsequent emit + /// (fail-closed) instead of retrying the seq — after a failure the on-disk suffix is unknown, + /// so a retry could append a duplicate seq behind a half-landed record and corrupt the chain + /// for verifiers. The first failure reports the IO error; later emits fail FAST naming the + /// poison. + #[test] + fn a_failed_durable_write_poisons_the_log_fail_closed() { + let path = std::env::temp_dir().join(format!("audit-poison-{}.log", std::process::id())); + std::fs::File::create(&path).unwrap(); + let ro = std::fs::OpenOptions::new().read(true).open(&path).unwrap(); + let log = AuditLog::with_file_handle(ro); + + let first = log.emit(AuditEvent::RuntimeStart { + timestamp: SecureTimestamp::now(), + version: "a".to_string(), + }); + assert!(first.is_err(), "read-only fd: the durable write must fail"); + + let second = log.emit(AuditEvent::RuntimeStart { + timestamp: SecureTimestamp::now(), + version: "b".to_string(), + }); + match second { + Err(e) => assert!( + e.to_string().contains("poisoned"), + "the second emit refuses fast, naming the poison: {e}" + ), + Ok(()) => panic!("a poisoned log must never accept another record"), + } + let _ = std::fs::remove_file(&path); + } + #[test] fn test_policy_proposal_event_serialization() { let event = AuditEvent::PolicyProposal { @@ -1995,4 +3562,358 @@ mod tests { }; assert_eq!(event.event_type_name(), "policy_divergence"); } + + /// Sprint 32: the responsible-entity binding rides the SIGNED CapabilityGrant record, so it is + /// in the receipt cryptographically. The load-bearing property is BACK-COMPAT: a pre-S32 grant + /// (no field) must re-serialize BYTE-IDENTICALLY — chain verification re-serializes deserialized + /// events to recompute each hash, so any drift silently breaks every old chain. + #[test] + fn responsible_entity_is_present_when_set_and_omitted_for_back_compat() { + // A pre-S32 record on disk: no `responsible_entity` key at all. + let legacy = r#"{"type":"capability_grant","timestamp":{"unix_secs":100,"monotonic_seq":0},"token_id":"abcd","capsule_id":"vm-a","resource":"elastos://x/y","action":"execute","expiry":null}"#; + let ev: AuditEvent = serde_json::from_str(legacy).unwrap(); + match &ev { + AuditEvent::CapabilityGrant { + responsible_entity, .. + } => { + assert!(responsible_entity.is_none(), "absent field ⇒ None"); + } + _ => panic!("wrong variant"), + } + // Re-serialization MUST be byte-identical to the signed original (skip_serializing_if). + assert_eq!( + serde_json::to_string(&ev).unwrap(), + legacy, + "a pre-S32 grant must re-serialize with NO responsible_entity key — else its chain hash \ + changes and every old receipt fails to verify" + ); + + // An S32 grant carries the DID verbatim, and it round-trips. + let bound = AuditEvent::CapabilityGrant { + timestamp: SecureTimestamp { + unix_secs: 100, + monotonic_seq: 0, + }, + token_id: "abcd".to_string(), + capsule_id: "vm-a".to_string(), + resource: "elastos://x/y".to_string(), + action: "execute".to_string(), + expiry: None, + responsible_entity: Some("did:web:acme.example".to_string()), + }; + let json = serde_json::to_string(&bound).unwrap(); + assert!( + json.contains("\"responsible_entity\":\"did:web:acme.example\""), + "a bound grant carries the liability DID in its signed record: {json}" + ); + // Round-trip (AuditEvent has no PartialEq — compare the canonical re-serialization). + let reparsed = serde_json::from_str::(&json).unwrap(); + assert_eq!(serde_json::to_string(&reparsed).unwrap(), json); + } + + /// Council S32 F1 belt: a REAL signed chain that MIXES a grant without the field (the pre-S32 + /// byte shape) and a grant with it (the S32 shape) verifies end-to-end against the signer — and + /// the field-less record's on-disk line carries NO responsible_entity key. This is the + /// whole-chain regression the pinned-literal event test complements: a field REORDER or an + /// omission-rule change breaks the recomputed hash and this fails. + #[test] + fn a_signed_chain_mixing_pre_and_post_s32_grants_verifies() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("audit.log"); + let log = AuditLog::with_file(&path).unwrap(); + // A pre-S32-shaped grant: responsible_entity None ⇒ omitted from the signed bytes. + log.emit(AuditEvent::CapabilityGrant { + timestamp: SecureTimestamp::now(), + token_id: "aaaa".to_string(), + capsule_id: "vm-a".to_string(), + resource: "elastos://x/y".to_string(), + action: "execute".to_string(), + expiry: None, + responsible_entity: None, + }) + .unwrap(); + // An S32 grant: the DID is in the signed bytes. + log.emit(AuditEvent::CapabilityGrant { + timestamp: SecureTimestamp::now(), + token_id: "bbbb".to_string(), + capsule_id: "vm-b".to_string(), + resource: "elastos://x/z".to_string(), + action: "execute".to_string(), + expiry: None, + responsible_entity: Some("did:web:acme.example".to_string()), + }) + .unwrap(); + let vk = read_verifying_key(&log); + assert!( + log.verify_chain(Some(&vk)).is_ok(), + "a chain mixing pre- and post-S32 grant shapes verifies end-to-end" + ); + let content = std::fs::read_to_string(&path).unwrap(); + let aaaa = content.lines().find(|l| l.contains("\"aaaa\"")).unwrap(); + assert!( + !aaaa.contains("responsible_entity"), + "a None grant's SIGNED line omits the field (byte-shape identical to pre-S32): {aaaa}" + ); + assert!(content + .lines() + .find(|l| l.contains("\"bbbb\"")) + .unwrap() + .contains("\"responsible_entity\":\"did:web:acme.example\"")); + } + + #[test] + fn rail_ref_is_present_when_set_and_omitted_for_back_compat() { + // A pre-S34 CapabilityUse on disk: no `rail_ref` key at all. + let legacy = r#"{"type":"capability_use","timestamp":{"unix_secs":100,"monotonic_seq":0},"token_id":"abcd","capsule_id":"vm-a","resource":"elastos://runtime/pay/acme","action":"execute","success":true}"#; + let ev: AuditEvent = serde_json::from_str(legacy).unwrap(); + match &ev { + AuditEvent::CapabilityUse { rail_ref, .. } => { + assert!(rail_ref.is_none(), "absent field ⇒ None"); + } + _ => panic!("wrong variant"), + } + // Re-serialization MUST be byte-identical (skip_serializing_if) — else every pre-S34 use + // record's chain hash changes and old receipts fail to verify. + assert_eq!( + serde_json::to_string(&ev).unwrap(), + legacy, + "a pre-S34 use must re-serialize with NO rail_ref key" + ); + + // An S34 use carries the reference verbatim, and it round-trips. + let settled = AuditEvent::CapabilityUse { + timestamp: SecureTimestamp { + unix_secs: 100, + monotonic_seq: 0, + }, + token_id: "abcd".to_string(), + capsule_id: "vm-a".to_string(), + resource: "elastos://runtime/pay/acme".to_string(), + action: "execute".to_string(), + success: true, + rail_ref: Some("drm:tx=0xdead;op=0xop;tid=42".to_string()), + }; + let json = serde_json::to_string(&settled).unwrap(); + assert!( + json.contains("\"rail_ref\":\"drm:tx=0xdead;op=0xop;tid=42\""), + "a settled use carries the rail reference in its signed record: {json}" + ); + let reparsed = serde_json::from_str::(&json).unwrap(); + assert_eq!(serde_json::to_string(&reparsed).unwrap(), json); + } + + /// Sprint 34 belt (mirrors the S32 mixed-chain fixture): a REAL signed chain mixing a + /// pre-S34-shaped `CapabilityUse` (no rail_ref) and an S34 one (with it) verifies end-to-end, + /// and the field-less record's on-disk line carries NO rail_ref key. + #[test] + fn a_signed_chain_mixing_pre_and_post_s34_uses_verifies() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("audit.log"); + let log = AuditLog::with_file(&path).unwrap(); + // A pre-S34-shaped use: rail_ref None ⇒ omitted from the signed bytes. + log.emit(AuditEvent::CapabilityUse { + timestamp: SecureTimestamp::now(), + token_id: "aaaa".to_string(), + capsule_id: "vm-a".to_string(), + resource: "elastos://runtime/audit-chain".to_string(), + action: "read".to_string(), + success: true, + rail_ref: None, + }) + .unwrap(); + // An S34 settled pay use: the tx reference is in the signed bytes. + log.emit(AuditEvent::CapabilityUse { + timestamp: SecureTimestamp::now(), + token_id: "bbbb".to_string(), + capsule_id: "vm-b".to_string(), + resource: "elastos://runtime/pay/acme".to_string(), + action: "execute".to_string(), + success: true, + rail_ref: Some("drm:tx=0xbeef;op=0xop;tid=7".to_string()), + }) + .unwrap(); + let vk = read_verifying_key(&log); + assert!( + log.verify_chain(Some(&vk)).is_ok(), + "a chain mixing pre- and post-S34 use shapes verifies end-to-end" + ); + let content = std::fs::read_to_string(&path).unwrap(); + let aaaa = content.lines().find(|l| l.contains("\"aaaa\"")).unwrap(); + assert!( + !aaaa.contains("rail_ref"), + "a None use's SIGNED line omits the field (byte-shape identical to pre-S34): {aaaa}" + ); + assert!(content + .lines() + .find(|l| l.contains("\"bbbb\"")) + .unwrap() + .contains("\"rail_ref\":\"drm:tx=0xbeef;op=0xop;tid=7\"")); + } + + /// Sprint 49 (the SPEC-mandate-v1 conformance ratchet): the WIRE FORMAT the spec documents is + /// pinned here — the schema tag, the three domain strings, every serialized key of the receipt + /// document / chained record / scope tags, and the mandate-relevant event shapes (including + /// the absent-when-unset rules old chains depend on). A change that breaks this test breaks + /// the published spec: mint a v2, never edit v1. + #[test] + fn the_wire_format_matches_spec_mandate_v1() { + // §2/§4 domain strings + the schema tag are part of the format. + assert_eq!(AUDIT_RECORD_DOMAIN, b"elastos.runtime/audit-chain/v1"); + assert_eq!( + MANDATE_RECEIPT_BINDING_DOMAIN, + b"elastos.runtime/mandate-receipt-set/v1" + ); + assert_eq!(MANDATE_RECEIPT_SCHEMA, "elastos.mandate_receipt/v1"); + + // A real capability receipt, serialized: the §3 document keys, exactly. + let dir = tempfile::tempdir().unwrap(); + let log = AuditLog::with_file(dir.path().join("audit.log")).unwrap(); + let token = crate::capability::token::TokenId::new(); + let vendor = crate::capability::ResourceId::new("elastos://pay/vendor"); + log.capability_grant( + &token, + "vm-agent", + &vendor, + crate::capability::token::Action::Write, + None, + ); + log.capability_use_with_rail_ref( + &token, + "vm-agent", + &vendor, + crate::capability::token::Action::Write, + true, + Some("erc20:tx=0xA;to=0xb;amount=1;tok=t".to_string()), + ); + let receipt = log + .export_mandate_receipt_for_capability(&token.to_string()) + .expect("receipt"); + let doc = serde_json::to_value(&receipt).unwrap(); + let mut doc_keys: Vec<_> = doc.as_object().unwrap().keys().cloned().collect(); + doc_keys.sort(); + assert_eq!( + doc_keys, + [ + "records", + "schema", + "scope", + "set_binding", + "signer_public_key_hex" + ], + "the §3 receipt document keys are frozen" + ); + // §3 scope tags. + assert_eq!( + serde_json::to_value(MandateReceiptScope::Contiguous).unwrap(), + serde_json::json!({"kind": "contiguous"}) + ); + assert_eq!( + doc["scope"]["kind"], "capability", + "capability scope tag: {:?}", + doc["scope"] + ); + assert!(doc["scope"]["token_id"].is_string()); + + // §2 chained-record keys, exactly. + let rec = &doc["records"][0]; + let mut rec_keys: Vec<_> = rec.as_object().unwrap().keys().cloned().collect(); + rec_keys.sort(); + assert_eq!( + rec_keys, + ["alg", "event", "prev_hash", "record_hash", "seq", "sig"], + "the §2 record keys are frozen" + ); + assert_eq!(rec["alg"], "ed25519"); + assert_eq!( + rec["prev_hash"].as_str().unwrap().len(), + 64, + "prev_hash is 64 hex chars (genesis = all zeros)" + ); + + // §5 event shapes: INTERNALLY tagged (`"type"`), snake_case; absent-when-unset rules. + let grant = &rec["event"]; + assert_eq!(grant["type"], "capability_grant"); + let mut grant_keys: Vec<_> = grant.as_object().unwrap().keys().cloned().collect(); + grant_keys.sort(); + assert_eq!( + grant_keys, + [ + "action", + "capsule_id", + "expiry", + "resource", + "timestamp", + "token_id", + "type" + ], + "capability_grant fields (responsible_entity ABSENT — not null — when unset)" + ); + let use_ev = &doc["records"][1]["event"]; + assert_eq!(use_ev["type"], "capability_use"); + let mut use_keys: Vec<_> = use_ev.as_object().unwrap().keys().cloned().collect(); + use_keys.sort(); + assert_eq!( + use_keys, + [ + "action", + "capsule_id", + "rail_ref", + "resource", + "success", + "timestamp", + "token_id", + "type" + ], + "capability_use fields (rail_ref present here because it was set)" + ); + // Timestamp shape (the §7 preimage depends on it too). + let ts = &grant["timestamp"]; + let mut ts_keys: Vec<_> = ts.as_object().unwrap().keys().cloned().collect(); + ts_keys.sort(); + assert_eq!( + ts_keys, + ["monotonic_seq", "unix_secs"], + "SecureTimestamp JSON shape is frozen" + ); + + // §5 revoke shape (S49 guardian F1 — the field list the first draft got wrong: there is + // NO capsule_id on a revoke) + BYTE-IDENTITY fixtures pinning field ORDER + compactness + // (S49 guardian F3): the hash preimage is these exact bytes, so order is normative. + let fixed_ts = elastos_common::SecureTimestamp { + unix_secs: 1_700_000_000, + monotonic_seq: 7, + }; + let grant_ev = AuditEvent::CapabilityGrant { + timestamp: fixed_ts, + token_id: "tok1".into(), + capsule_id: "vm-a".into(), + resource: "elastos://pay/v".into(), + action: "write".into(), + expiry: None, + responsible_entity: None, + }; + assert_eq!( + serde_json::to_string(&grant_ev).unwrap(), + "{\"type\":\"capability_grant\",\"timestamp\":{\"unix_secs\":1700000000,\ + \"monotonic_seq\":7},\"token_id\":\"tok1\",\"capsule_id\":\"vm-a\",\ + \"resource\":\"elastos://pay/v\",\"action\":\"write\",\"expiry\":null}", + "capability_grant byte template (§5) — type first, declared order, compact, \ + expiry:null when unset, responsible_entity ABSENT when unset" + ); + let revoke_ev = AuditEvent::CapabilityRevoke { + timestamp: fixed_ts, + token_id: "tok1".into(), + reason: "kill switch".into(), + }; + assert_eq!( + serde_json::to_string(&revoke_ev).unwrap(), + "{\"type\":\"capability_revoke\",\"timestamp\":{\"unix_secs\":1700000000,\ + \"monotonic_seq\":7},\"token_id\":\"tok1\",\"reason\":\"kill switch\"}", + "capability_revoke byte template (§5) — exactly type/timestamp/token_id/reason" + ); + + // And the exported receipt verifies — the spec's §6 algorithm against its own §2-§4 shapes. + let signer = log.verifying_key_hex().unwrap(); + assert!(verify_mandate_receipt(&receipt, Some(&signer)).authenticated); + } } diff --git a/elastos/crates/elastos-runtime/src/primitives/mod.rs b/elastos/crates/elastos-runtime/src/primitives/mod.rs index 0faadb35..ca1201b5 100644 --- a/elastos/crates/elastos-runtime/src/primitives/mod.rs +++ b/elastos/crates/elastos-runtime/src/primitives/mod.rs @@ -8,11 +8,10 @@ pub mod metrics; pub mod spend; pub mod time; -#[allow(unused_imports)] -pub use audit::{AuditEvent, AuditLog, ChainAttestation}; -#[allow(unused_imports)] +pub use audit::{ + verify_mandate_receipt, AuditEvent, AuditLog, ChainAttestation, MandateReceipt, + MandateReceiptScope, MandateReceiptVerdict, +}; pub use metrics::CapsuleMetrics; -#[allow(unused_imports)] pub use spend::{BudgetSnapshot, SpendError, SpendMeter, SpendUnits}; -#[allow(unused_imports)] pub use time::SecureTimestamp; diff --git a/elastos/crates/elastos-runtime/src/primitives/spend.rs b/elastos/crates/elastos-runtime/src/primitives/spend.rs index 469b0660..4918619c 100644 --- a/elastos/crates/elastos-runtime/src/primitives/spend.rs +++ b/elastos/crates/elastos-runtime/src/primitives/spend.rs @@ -20,8 +20,27 @@ //! //! FAIL-CLOSED DEFAULT: an unprovisioned key has ZERO budget, not unlimited — an unknown capsule //! cannot spend. Provisioning ([`SpendMeter::set_budget`]) is an explicit act. +//! +//! DURABILITY (council Sprint 27 F1, closed Sprint 28): the meter has TWO modes, mirroring +//! `StandingGrantStore`: +//! +//! - **In-memory** ([`SpendMeter::new`]) — for rate/credit limiting (the carrier act path), where a +//! restart refilling the budget is the safe/generous direction and a per-act fsync would be an +//! unacceptable flood. Mutations never fail. +//! - **Durable** ([`SpendMeter::open_durable`]) — for a MONEY cap, where a restart refilling the cap +//! would let the intended cumulative limit be exceeded. Every balance mutation is snapshot+fsync'd +//! (temp + fsync + rename + parent-dir fsync, durable-before-visible) BEFORE it takes effect; a +//! debit whose reservation cannot be recorded is REFUSED and debits nothing +//! ([`SpendError::Persist`]), so money never moves against a balance that would not survive a +//! restart. A corrupt snapshot refuses to open (fail-closed) rather than booting with a silently +//! refilled cap. +//! +//! The REAL rail connector exists as of Sprint 29 (`HttpPaymentProvider`, wired via +//! `ELASTOS_PAYMENT_ENDPOINT` and REQUIRING this durable mode); the Mock rail remains dev/demo-gated +//! (`ELASTOS_ALLOW_MOCK_PAYMENTS`). use std::collections::HashMap; +use std::path::PathBuf; use std::sync::RwLock; /// A whole-number quantity of spend (AI tokens, request credits, …). `u64` so a balance can never @@ -51,6 +70,17 @@ pub enum SpendError { /// The balance lock was poisoned by a panicking thread — refuse to debit rather than risk an /// unbounded spend against a possibly-torn balance. Lock, + /// A durable meter could not persist the mutation. The mutation was ROLLED BACK — a reservation + /// that would not survive a restart is never granted (in-memory mode never returns this). + Persist, + /// The durable meter is POISONED: a persist failed AFTER the rename published the new snapshot + /// (council S28 F1). The mutation that poisoned IS in the visible snapshot and in memory (they + /// agree — see the module doc), but its power-cut protection is missing, so all further + /// mutations refuse until the meter is reopened from disk — in practice, a process restart + /// (the live meter's own single-opener flock forbids opening a replacement). Fail-closed; + /// reads still project. Returned BOTH by the mutation that poisoned and by every mutation + /// after it (council S29 F1: the poisoning call must not claim a rollback that didn't happen). + Poisoned, } impl std::fmt::Display for SpendError { @@ -65,6 +95,17 @@ impl std::fmt::Display for SpendError { ), SpendError::NoBudget => write!(f, "no spend budget provisioned for this key"), SpendError::Lock => write!(f, "spend meter lock poisoned"), + SpendError::Persist => write!( + f, + "spend meter could not durably record the mutation; it was rolled back" + ), + SpendError::Poisoned => write!( + f, + "spend meter is poisoned: a persist failed after publishing the new snapshot — \ + the last mutation IS in the visible snapshot but its power-cut protection is \ + missing; mutations refuse until the meter is reopened from disk (in practice: \ + restart the process)" + ), } } } @@ -83,14 +124,70 @@ impl Balance { } } +/// One key's balance as it appears in the durable snapshot (sorted by key for determinism). +#[derive(serde::Serialize, serde::Deserialize)] +struct BalanceRecord { + key: String, + limit: SpendUnits, + spent: SpendUnits, +} + +/// The versioned on-disk snapshot of a durable meter. +#[derive(serde::Serialize, serde::Deserialize)] +struct SpendSnapshotV1 { + version: u32, + balances: Vec, +} + +const SPEND_SNAPSHOT_VERSION: u32 = 1; + +/// How a durable persist failed — the distinction council S28 F1 demanded. Before the rename, the +/// OLD snapshot is still the visible file, so rolling back memory restores exact agreement. After +/// the rename the NEW snapshot is published; only the parent-dir fsync (power-cut protection) is +/// missing, so memory must KEEP the mutation (it matches the visible disk) and the meter must +/// POISON (a power cut could still revert the publish — no further mutation may stack on that). +enum PersistFailure { + PrePublish, + PostPublish, +} + /// A per-key spend budget with atomic, fail-closed debit and a provably-no-op refund. /// /// All mutations take a single write lock and complete in one statement, so the balance map is never /// observed half-updated; a debit can never race another into an overspend (proven by /// `tests::concurrent_debits_never_overspend`). +/// +/// In DURABLE mode ([`open_durable`](Self::open_durable)) every mutation is persisted under that +/// same write lock, durable-before-visible: on a persist failure the mutation is rolled back in +/// memory and surfaced ([`SpendError::Persist`]) — money never moves against a reservation only +/// memory holds. +/// +/// POST-PUBLISH failures (council S28 F1, closed S29): when a persist fails AFTER the rename has +/// published the new snapshot (only the parent-dir power-cut fsync missing), memory KEEPS the +/// mutation — it matches the visible disk, so no divergence — and the meter POISONS: every further +/// mutation refuses ([`SpendError::Poisoned`]) until reopened from disk, because stacking more +/// mutations on a publish a power cut could revert would compound the revert window. `try_debit` +/// still refuses the payment in that case (the reservation stays on disk — an orphaned-reservation +/// shape the operator repairs by raising the limit); `try_refund` reports the refund in force +/// (memory and visible disk agree; the only residual, a power-cut revert to the MORE-spent +/// snapshot, is the fail-closed direction). #[derive(Default)] pub struct SpendMeter { balances: RwLock>, + /// `Some` ⇒ durable mode: every mutation snapshots to this path before taking effect. + storage_path: Option, + /// Set when a persist failed AFTER publish (council S28 F1): memory matches the visible disk, + /// but a power cut could revert the publish — every further mutation refuses ([`SpendError:: + /// Poisoned`]) until the meter is reopened from disk. Reads keep projecting. + poisoned: std::sync::atomic::AtomicBool, + /// Held for the meter's lifetime: an exclusive advisory flock on `.lock` (council S28 + /// F4), so single-opener no longer depends on the caller's host-lock discipline — a second + /// opener of the same snapshot fails at `open_durable`, never last-writer-wins clobbering. + _lock_file: Option, + /// TEST SEAM: force the next persists to fail post-publish (the parent-dir fsync erroring + /// after a successful rename — unreachable from outside without root-only permission games). + #[cfg(test)] + fail_parent_fsync: std::sync::atomic::AtomicBool, } impl SpendMeter { @@ -98,33 +195,296 @@ impl SpendMeter { Self::default() } + /// Open a DURABLE meter backed by `path` (the money mode). A missing file is a fresh, empty + /// meter (every key fail-closed at zero until provisioned); an existing snapshot restores every + /// balance INCLUDING `spent` — a restart never refills a cap. A corrupt, oversized, duplicated, + /// or unreadable snapshot REFUSES to open (fail-closed): booting a money meter with silently + /// zeroed spend would let the cumulative cap be exceeded, exactly what durability exists to + /// prevent. + /// + /// STATED BOUND (council S28): the snapshot is NOT self-authenticating — unlike the signed + /// audit chain, anyone who can write `data_dir` can forge it (the same trust boundary as the + /// runtime's key material; a hostile disk already owns the box). SINGLE-OPENER is enforced here + /// (S29, council F4): an exclusive advisory flock on `.lock` is held for the meter's + /// lifetime, so a second opener fails fail-closed instead of last-writer-wins clobbering the + /// other's `spent` — independent of the serve/gateway host lock. + pub fn open_durable(path: PathBuf) -> std::io::Result { + #[cfg(unix)] + let lock_file = { + use std::os::unix::io::AsRawFd as _; + let lock_path = path.with_extension("lock"); + let f = std::fs::OpenOptions::new() + .create(true) + .truncate(false) // the lock file carries no content; never disturb it + .write(true) + .open(&lock_path)?; + let rc = unsafe { libc::flock(f.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) }; + if rc != 0 { + return Err(std::io::Error::new( + std::io::ErrorKind::WouldBlock, + "spend meter snapshot is already open elsewhere (single-opener, fail-closed)", + )); + } + Some(f) + }; + #[cfg(not(unix))] + let lock_file = None; + let mut balances = HashMap::new(); + match std::fs::read(&path) { + Ok(bytes) => { + // Size bound before parse: a money meter has at most a few thousand keys; a huge + // file is a forgery/corruption, not a balance set — refuse rather than OOM at boot. + if bytes.len() > 4 * 1024 * 1024 { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidData, + "spend snapshot exceeds the 4 MiB bound", + )); + } + let snapshot: SpendSnapshotV1 = serde_json::from_slice(&bytes) + .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?; + if snapshot.version != SPEND_SNAPSHOT_VERSION { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidData, + format!("unsupported spend snapshot version {}", snapshot.version), + )); + } + for rec in snapshot.balances { + // A duplicate key would silently last-write-win a balance away — the writer + // never produces one (it serializes a map), so a dup is tampering: refuse. + if balances + .insert( + rec.key.clone(), + Balance { + limit: rec.limit, + spent: rec.spent, + }, + ) + .is_some() + { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidData, + format!("duplicate key {:?} in spend snapshot", rec.key), + )); + } + } + } + Err(e) if e.kind() == std::io::ErrorKind::NotFound => {} + Err(e) => return Err(e), + } + Ok(Self { + balances: RwLock::new(balances), + storage_path: Some(path), + poisoned: std::sync::atomic::AtomicBool::new(false), + _lock_file: lock_file, + #[cfg(test)] + fail_parent_fsync: std::sync::atomic::AtomicBool::new(false), + }) + } + + /// True once a persist has failed post-publish ([`SpendError::Poisoned`]) — mutations refuse; + /// reopen from disk to recover. Surfaces so a wiring/ops layer can alarm on it. + pub fn is_poisoned(&self) -> bool { + self.poisoned.load(std::sync::atomic::Ordering::SeqCst) + } + + /// TEST SEAM (never production): force the poisoned state, so downstream crates' ratchets can + /// exercise poisoned-path behavior (e.g. the reconcile surface refusing a refund) without the + /// root-only filesystem games a real post-publish failure needs — the same precedent as + /// `AuditLog::with_file_handle`. Production code poisons ONLY via `persist_locked`. + #[doc(hidden)] + pub fn poison_for_tests(&self) { + self.poison(); + } + + fn refuse_if_poisoned(&self) -> Result<(), SpendError> { + if self.is_poisoned() { + return Err(SpendError::Poisoned); + } + Ok(()) + } + + /// True when this meter persists every mutation ([`open_durable`](Self::open_durable)) — the + /// property a MONEY cap requires. Lets a wiring layer refuse to put real spend on a meter that + /// would refill across restart. + pub fn is_durable(&self) -> bool { + self.storage_path.is_some() + } + + /// Write the full snapshot atomically (temp + fsync + rename + parent-dir fsync), mirroring + /// `StandingGrantStore::persist_locked`. Called with the write guard held so the serialized + /// state is exactly the state that becomes visible. Memory-only ⇒ no-op. + /// + /// The failure REPORTS which side of the rename it happened on (council S28 F1): `PrePublish` + /// means the old snapshot is still the visible file (caller rolls memory back — exact agreement + /// restored); `PostPublish` means the NEW snapshot is published and only the power-cut + /// protection (parent-dir fsync) is missing (caller keeps memory and POISONS the meter). + fn persist_locked(&self, balances: &HashMap) -> Result<(), PersistFailure> { + let Some(path) = &self.storage_path else { + return Ok(()); + }; + let mut records: Vec = balances + .iter() + .map(|(key, b)| BalanceRecord { + key: key.clone(), + limit: b.limit, + spent: b.spent, + }) + .collect(); + records.sort_by(|a, b| a.key.cmp(&b.key)); + let Ok(content) = serde_json::to_vec(&SpendSnapshotV1 { + version: SPEND_SNAPSHOT_VERSION, + balances: records, + }) else { + return Err(PersistFailure::PrePublish); + }; + let tmp_path = path.with_extension("tmp"); + let write_and_sync = || -> std::io::Result<()> { + use std::io::Write as _; + let mut tmp = std::fs::File::create(&tmp_path)?; + tmp.write_all(&content)?; + // Durable BEFORE visible: the rename must never publish bytes still in the page cache. + tmp.sync_all() + }; + if write_and_sync().is_err() { + return Err(PersistFailure::PrePublish); + } + if std::fs::rename(&tmp_path, path).is_err() { + return Err(PersistFailure::PrePublish); + } + // PUBLISHED from here on. Without fsyncing the parent directory, a power cut can revert the + // entry to the OLD snapshot — for a money meter that revert is a refilled cap (an + // already-reserved spend disappears), so the fsync is part of the write, not a nicety. + #[cfg(test)] + if self + .fail_parent_fsync + .load(std::sync::atomic::Ordering::SeqCst) + { + return Err(PersistFailure::PostPublish); + } + #[cfg(unix)] + if let Some(parent) = path.parent() { + let synced = std::fs::File::open(parent).and_then(|d| d.sync_all()); + if synced.is_err() { + return Err(PersistFailure::PostPublish); + } + } + Ok(()) + } + + /// Shared post-publish handling: memory KEEPS the mutation (it matches the visible disk) and + /// the meter poisons — no further mutation may stack on a publish a power cut could revert. + fn poison(&self) { + self.poisoned + .store(true, std::sync::atomic::Ordering::SeqCst); + } + /// Provision (or re-set) a key's TOTAL budget. Raising the limit grants more headroom; lowering /// it below what is already spent simply clamps remaining to zero (never refunds silently). - pub fn set_budget(&self, key: &str, limit: SpendUnits) { + /// Durable mode: persisted before returning `Ok`; a persist failure rolls the limit back and + /// returns [`SpendError::Persist`] (in-memory mode never fails). + /// + /// Returns the PRIOR limit (`None` = the key was unprovisioned), read under the same write lock + /// as the mutation — the one linearizable old-value an attestation and a rollback can both trust + /// (council S28 F6: two lock-free `snapshot()` reads let concurrent provisions attest the same + /// stale "old"). + pub fn set_budget( + &self, + key: &str, + limit: SpendUnits, + ) -> Result, SpendError> { + self.refuse_if_poisoned()?; let mut balances = match self.balances.write() { Ok(b) => b, // A poisoned lock here can only mean a prior panic; the map is structurally intact // (every write is one statement), so recover the guard rather than drop provisioning. Err(poisoned) => poisoned.into_inner(), }; + let prior = balances.get(key).copied(); balances .entry(key.to_string()) .and_modify(|b| b.limit = limit) .or_insert(Balance { limit, spent: 0 }); + match self.persist_locked(&balances) { + Ok(()) => Ok(prior.map(|b| b.limit)), + Err(PersistFailure::PrePublish) => { + match prior { + Some(bal) => { + balances.insert(key.to_string(), bal); + } + None => { + balances.remove(key); + } + } + Err(SpendError::Persist) + } + Err(PersistFailure::PostPublish) => { + // The new limit IS the visible disk state — keep memory in agreement, poison, and + // refuse with the HONEST variant (council S29 F1: `Persist` claims a rollback + // that did not happen here). The caller's loud double-failure path handles it. + self.poison(); + Err(SpendError::Poisoned) + } + } + } + + /// Remove a key's budget entirely (durable, same rollback discipline): afterwards the key is + /// UNPROVISIONED — fail-closed `NoBudget`, `snapshot() == None` — exactly as if it had never + /// been set. Returns whether the key existed. Exists so a provisioning surface can truly undo a + /// failed first-time provision (council S28 F7: rolling an unprovisioned key "back" to limit 0 + /// leaves an enumerable provisioned-at-zero artifact the chain never granted). + pub fn remove_budget(&self, key: &str) -> Result { + self.refuse_if_poisoned()?; + let mut balances = match self.balances.write() { + Ok(b) => b, + Err(poisoned) => poisoned.into_inner(), + }; + let Some(prior) = balances.remove(key) else { + return Ok(false); + }; + match self.persist_locked(&balances) { + Ok(()) => Ok(true), + Err(PersistFailure::PrePublish) => { + balances.insert(key.to_string(), prior); + Err(SpendError::Persist) + } + Err(PersistFailure::PostPublish) => { + // The removal IS published; honest variant, same rule as set_budget (S29 F1). + self.poison(); + Err(SpendError::Poisoned) + } + } } /// Provision `key` with `limit` ONLY if it has no budget yet (idempotent first-touch). Unlike /// [`set_budget`](Self::set_budget) this NEVER disturbs an existing budget's limit or spent — so /// it is safe to call on every act to lazily provision a per-capsule default without ever - /// resetting accumulated spend. - pub fn ensure_budget(&self, key: &str, limit: SpendUnits) { + /// resetting accumulated spend. Durable mode: persists only when it actually inserted; a + /// PRE-publish persist failure rolls the insert back (the key stays unprovisioned ⇒ fail-closed + /// `NoBudget` on debit), while a POST-publish failure poisons the meter and reports `Poisoned` + /// — the insert IS published, so claiming a rollback would be a lie (same rule as + /// [`set_budget`](Self::set_budget), S29 F1). + pub fn ensure_budget(&self, key: &str, limit: SpendUnits) -> Result<(), SpendError> { + self.refuse_if_poisoned()?; let mut balances = match self.balances.write() { Ok(b) => b, Err(poisoned) => poisoned.into_inner(), }; - balances - .entry(key.to_string()) - .or_insert(Balance { limit, spent: 0 }); + if balances.contains_key(key) { + return Ok(()); + } + balances.insert(key.to_string(), Balance { limit, spent: 0 }); + match self.persist_locked(&balances) { + Ok(()) => Ok(()), + Err(PersistFailure::PrePublish) => { + balances.remove(key); + Err(SpendError::Persist) + } + Err(PersistFailure::PostPublish) => { + // The insert IS published; `Persist` would falsely claim a rollback (S29 F1). + self.poison(); + Err(SpendError::Poisoned) + } + } } /// Remaining budget for `key` (0 if unprovisioned). @@ -135,6 +495,33 @@ impl SpendMeter { } } + /// Every provisioned key's [`BudgetSnapshot`], sorted by key — the list projection an operator + /// surface renders (the Money panel). OBSERVE-only, like [`snapshot`](Self::snapshot). + pub fn snapshot_all(&self) -> Vec<(String, BudgetSnapshot)> { + // A panic-poisoned lock still holds a structurally intact map (every write is one + // statement) — recover like the writers do, rather than fabricating "no budgets + // provisioned" on an operator money surface (council S31 G-F9). + let balances = match self.balances.read() { + Ok(b) => b, + Err(poisoned) => poisoned.into_inner(), + }; + let mut out: Vec<(String, BudgetSnapshot)> = balances + .iter() + .map(|(k, b)| { + ( + k.clone(), + BudgetSnapshot { + limit: b.limit, + spent: b.spent, + remaining: b.remaining(), + }, + ) + }) + .collect(); + out.sort_by(|a, b| a.0.cmp(&b.0)); + out + } + /// A read-only [`BudgetSnapshot`] of `key` for projection (UI / inspector / API). `None` if the /// key has no provisioned budget. OBSERVE-only — it never mutates; the meter stays the single /// source of truth the projection reflects. @@ -150,7 +537,13 @@ impl SpendMeter { /// Atomically debit `cost` from `key` if it fits, else refuse and debit NOTHING. On success /// returns the remaining budget AFTER the debit. `cost == 0` is always allowed (a no-op debit); /// `cost == remaining` is allowed (spends to exactly zero). + /// + /// Durable mode: the debit is PERSISTED before `Ok` returns — the reservation survives a crash + /// between this call and the spending action, so the action can never replay against a refilled + /// cap. A persist failure rolls the debit back and refuses ([`SpendError::Persist`]): money must + /// not move on a reservation the disk does not hold. pub fn try_debit(&self, key: &str, cost: SpendUnits) -> Result { + self.refuse_if_poisoned()?; let mut balances = self.balances.write().map_err(|_| SpendError::Lock)?; let bal = balances.get_mut(key).ok_or(SpendError::NoBudget)?; let remaining = bal.remaining(); @@ -162,7 +555,24 @@ impl SpendMeter { } // cost <= remaining = limit - spent, so spent + cost <= limit: no overflow. bal.spent += cost; - Ok(bal.remaining()) + let after = bal.remaining(); + match self.persist_locked(&balances) { + Ok(()) => Ok(after), + Err(PersistFailure::PrePublish) => { + if let Some(bal) = balances.get_mut(key) { + bal.spent = bal.spent.saturating_sub(cost); + } + Err(SpendError::Persist) + } + Err(PersistFailure::PostPublish) => { + // The debit IS the visible disk state, but its power-cut protection is missing — + // refuse the payment (fail-closed; the reservation stays, an orphaned-reservation + // shape the operator can repair) and poison against further churn. The HONEST + // variant (S29 F1): `Persist` would claim a rollback that did not happen. + self.poison(); + Err(SpendError::Poisoned) + } + } } /// Debit up to `amount`, draining no further than zero, and return the amount ACTUALLY debited @@ -170,19 +580,31 @@ impl SpendMeter { /// has ALREADY happened (e.g. a provider reporting the units it actually consumed): the act can /// no longer be refused, so an over-budget cost drains the remainder and the next act is refused /// fail-closed by [`try_debit`]. Unprovisioned/poisoned ⇒ debits nothing. + /// + /// Durable mode: the debit stays in force even if the persist fails (the action ALREADY + /// happened — rolling back would grant headroom the world has already consumed); the snapshot + /// catches up at the next successful mutation. The reservation path a MONEY act depends on is + /// [`try_debit`], which is strictly durable-before-visible. pub fn debit_saturating(&self, key: &str, amount: SpendUnits) -> SpendUnits { + if self.is_poisoned() { + return 0; + } let mut balances = match self.balances.write() { Ok(b) => b, Err(_) => return 0, }; - match balances.get_mut(key) { + let take = match balances.get_mut(key) { Some(bal) => { let take = amount.min(bal.remaining()); bal.spent += take; take } - None => 0, + None => return 0, + }; + if let Err(PersistFailure::PostPublish) = self.persist_locked(&balances) { + self.poison(); } + take } /// Refund a prior debit (saturating). ONLY for a charge whose action provably did NOT occur — @@ -191,17 +613,49 @@ impl SpendMeter { /// /// Conservative under failure: an unknown key or a poisoned lock credits nothing back (a meter /// erring toward *more* spent / *less* available is the fail-closed direction for a budget). + /// Durable mode: a refund whose persist fails is ROLLED BACK in memory (not granted) — the + /// fail-closed direction. Callers that must RECORD whether the refund actually stuck (a money + /// path minting a signed reason) use [`try_refund`](Self::try_refund), which distinguishes the + /// rollback; this convenience face only reports the resulting remaining. pub fn refund(&self, key: &str, cost: SpendUnits) -> SpendUnits { - let mut balances = match self.balances.write() { - Ok(b) => b, - Err(_) => return 0, - }; - match balances.get_mut(key) { + match self.try_refund(key, cost) { + Ok(remaining) => remaining, + Err(_) => self.remaining(key), + } + } + + /// [`refund`](Self::refund) with an honest failure channel: `Ok(remaining)` iff the refund is + /// IN FORCE (and, on a durable meter, persisted); `Err(Persist)` when it was rolled back + /// (the cap REMAINS DEBITED), `Err(NoBudget)`/`Err(Lock)` when nothing could be credited. A + /// signed record derived from this call must only claim "refunded" on `Ok` (council S28 F3: the + /// pay path's Declined reason said "spend refunded" even when the durable refund rolled back). + pub fn try_refund(&self, key: &str, cost: SpendUnits) -> Result { + self.refuse_if_poisoned()?; + let mut balances = self.balances.write().map_err(|_| SpendError::Lock)?; + let (refunded, remaining) = match balances.get_mut(key) { Some(bal) => { + let before = bal.spent; bal.spent = bal.spent.saturating_sub(cost); - bal.remaining() + (before - bal.spent, bal.remaining()) + } + None => return Err(SpendError::NoBudget), + }; + match self.persist_locked(&balances) { + Ok(()) => Ok(remaining), + Err(PersistFailure::PrePublish) => { + if let Some(bal) = balances.get_mut(key) { + bal.spent += refunded; + } + Err(SpendError::Persist) + } + Err(PersistFailure::PostPublish) => { + // The refund IS in force (memory and the visible disk agree) — claiming otherwise + // would be false — but poison against stacking further mutations on an unfsynced + // publish. The only residual is a power-cut revert to the MORE-spent snapshot, + // which is the fail-closed direction. + self.poison(); + Ok(remaining) } - None => 0, } } } @@ -214,7 +668,7 @@ mod tests { #[test] fn debit_within_budget_decrements_remaining() { let meter = SpendMeter::new(); - meter.set_budget("vm-alice", 100); + meter.set_budget("vm-alice", 100).unwrap(); assert_eq!(meter.remaining("vm-alice"), 100); assert_eq!(meter.try_debit("vm-alice", 30).unwrap(), 70); assert_eq!( @@ -228,7 +682,7 @@ mod tests { #[test] fn debit_over_budget_is_refused_and_charges_nothing() { let meter = SpendMeter::new(); - meter.set_budget("vm-alice", 50); + meter.set_budget("vm-alice", 50).unwrap(); meter.try_debit("vm-alice", 40).unwrap(); let err = meter.try_debit("vm-alice", 20).unwrap_err(); assert_eq!( @@ -267,7 +721,7 @@ mod tests { #[test] fn refund_restores_only_what_was_spent() { let meter = SpendMeter::new(); - meter.set_budget("vm-alice", 100); + meter.set_budget("vm-alice", 100).unwrap(); meter.try_debit("vm-alice", 60).unwrap(); assert_eq!( meter.refund("vm-alice", 60), @@ -282,9 +736,9 @@ mod tests { #[test] fn lowering_budget_below_spent_clamps_remaining_to_zero() { let meter = SpendMeter::new(); - meter.set_budget("vm-alice", 100); + meter.set_budget("vm-alice", 100).unwrap(); meter.try_debit("vm-alice", 80).unwrap(); - meter.set_budget("vm-alice", 50); // below the 80 already spent + meter.set_budget("vm-alice", 50).unwrap(); // below the 80 already spent assert_eq!(meter.remaining("vm-alice"), 0, "clamped, never negative"); assert_eq!( meter.try_debit("vm-alice", 1).unwrap_err(), @@ -303,7 +757,7 @@ mod tests { None, "an unprovisioned key has no budget to project" ); - meter.set_budget("vm-alice", 100); + meter.set_budget("vm-alice", 100).unwrap(); meter.try_debit("vm-alice", 30).unwrap(); assert_eq!( meter.snapshot("vm-alice"), @@ -318,7 +772,7 @@ mod tests { #[test] fn debit_saturating_drains_to_zero_and_reports_actual() { let meter = SpendMeter::new(); - meter.set_budget("vm-alice", 10); + meter.set_budget("vm-alice", 10).unwrap(); assert_eq!( meter.debit_saturating("vm-alice", 3), 3, @@ -341,10 +795,10 @@ mod tests { #[test] fn ensure_budget_provisions_once_and_never_resets_spend() { let meter = SpendMeter::new(); - meter.ensure_budget("vm-alice", 100); + meter.ensure_budget("vm-alice", 100).unwrap(); meter.try_debit("vm-alice", 40).unwrap(); // A second ensure_budget (even with a different limit) must NOT reset the 40 already spent. - meter.ensure_budget("vm-alice", 5); + meter.ensure_budget("vm-alice", 5).unwrap(); assert_eq!( meter.remaining("vm-alice"), 60, @@ -357,7 +811,7 @@ mod tests { // 64 threads each try to debit 1 from a budget of 40. EXACTLY 40 may succeed — the atomic // check-and-debit must never let the 41st through (the property the meter exists to hold). let meter = Arc::new(SpendMeter::new()); - meter.set_budget("vm-alice", 40); + meter.set_budget("vm-alice", 40).unwrap(); let mut handles = Vec::new(); for _ in 0..64 { let m = Arc::clone(&meter); @@ -373,4 +827,302 @@ mod tests { assert_eq!(granted, 40, "exactly the budget was granted, never more"); assert_eq!(meter.remaining("vm-alice"), 0); } + + // === Durable mode (Sprint 28 — the money-cap prerequisites) === + + #[test] + fn durable_meter_restart_never_refills_the_cap() { + // THE money property (council Sprint 27 F1): spend survives a restart. A cap of 500 with + // 200 already spent must come back as 300 remaining — never a fresh 500. + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("spend_meter.json"); + { + let meter = SpendMeter::open_durable(path.clone()).unwrap(); + assert!(meter.is_durable()); + meter.set_budget("vm-ap-agent", 500).unwrap(); + assert_eq!(meter.try_debit("vm-ap-agent", 200).unwrap(), 300); + } // restart + let reopened = SpendMeter::open_durable(path).unwrap(); + assert_eq!( + reopened.remaining("vm-ap-agent"), + 300, + "the 200 spent before the restart is still spent after it" + ); + assert!( + matches!( + reopened.try_debit("vm-ap-agent", 400), + Err(SpendError::Exhausted { remaining: 300, .. }) + ), + "an over-remaining debit is still refused across the restart boundary" + ); + // An unprovisioned key stays fail-closed after reopen, exactly like a fresh meter. + assert_eq!( + reopened.try_debit("vm-ghost", 1).unwrap_err(), + SpendError::NoBudget + ); + } + + #[test] + fn durable_meter_refuses_a_corrupt_snapshot() { + // Fail-closed boot: a money meter must never open over a snapshot it cannot parse — that + // would silently zero `spent` and refill every cap. Missing file (fresh install) is fine. + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("spend_meter.json"); + std::fs::write(&path, b"{ not json").unwrap(); + assert!( + SpendMeter::open_durable(path.clone()).is_err(), + "a corrupt snapshot refuses to open" + ); + std::fs::write( + &path, + serde_json::to_vec(&SpendSnapshotV1 { + version: 999, + balances: vec![], + }) + .unwrap(), + ) + .unwrap(); + assert!( + SpendMeter::open_durable(path).is_err(), + "an unknown snapshot version refuses to open" + ); + assert!( + SpendMeter::open_durable(dir.path().join("absent.json")).is_ok(), + "a missing file is a fresh empty meter, not an error" + ); + } + + #[test] + fn durable_debit_that_cannot_persist_is_refused_and_rolled_back() { + // Durable-before-visible: if the reservation cannot land on disk, the debit must be REFUSED + // and the in-memory balance unchanged — money must never move on a reservation only memory + // holds. Forced by destroying the snapshot's directory between provisioning and the debit. + let dir = tempfile::tempdir().unwrap(); + let sub = dir.path().join("meter"); + std::fs::create_dir(&sub).unwrap(); + let meter = SpendMeter::open_durable(sub.join("spend_meter.json")).unwrap(); + meter.set_budget("vm-ap-agent", 500).unwrap(); + std::fs::remove_dir_all(&sub).unwrap(); // the persist target is now unwritable + assert_eq!( + meter.try_debit("vm-ap-agent", 200).unwrap_err(), + SpendError::Persist, + "a debit whose reservation cannot persist is refused" + ); + assert_eq!( + meter.remaining("vm-ap-agent"), + 500, + "the refused debit was rolled back — nothing reserved" + ); + // Provisioning is equally fail-closed: a set_budget that cannot persist rolls back. + assert_eq!( + meter.set_budget("vm-new", 100).unwrap_err(), + SpendError::Persist + ); + assert_eq!( + meter.try_debit("vm-new", 1).unwrap_err(), + SpendError::NoBudget, + "the failed provisioning left no budget behind" + ); + } + + #[test] + fn durable_refund_that_cannot_persist_is_rolled_back_in_memory() { + // The refund mirror: headroom memory shows but disk would revoke on restart is a phantom + // refund — on a persist failure the refund is rolled back IN MEMORY (fail-closed = LESS + // available), and try_refund SURFACES it so a signed record never claims "refunded" for a + // refund that is not in force (council S28 F3). Honest bound: this asserts the in-memory + // outcome; a post-PUBLISH persist failure can leave the refund on disk (module doc, F1). + let dir = tempfile::tempdir().unwrap(); + let sub = dir.path().join("meter"); + std::fs::create_dir(&sub).unwrap(); + let meter = SpendMeter::open_durable(sub.join("spend_meter.json")).unwrap(); + meter.set_budget("vm-ap-agent", 500).unwrap(); + meter.try_debit("vm-ap-agent", 200).unwrap(); + std::fs::remove_dir_all(&sub).unwrap(); + assert_eq!( + meter.try_refund("vm-ap-agent", 200).unwrap_err(), + SpendError::Persist, + "the money path is TOLD the refund did not stick — the cap remains debited" + ); + assert_eq!( + meter.refund("vm-ap-agent", 200), + 300, + "the convenience face reports the unchanged remaining after the rollback" + ); + assert_eq!(meter.remaining("vm-ap-agent"), 300); + } + + #[test] + fn set_budget_returns_the_prior_limit_read_under_the_lock() { + // Council S28 F6: the attestation's old→new must be linearizable against the mutation, so + // the prior comes back from set_budget itself, not a separate racy read. + let meter = SpendMeter::new(); + assert_eq!( + meter.set_budget("vm-alice", 100).unwrap(), + None, + "first provision: no prior" + ); + assert_eq!( + meter.set_budget("vm-alice", 250).unwrap(), + Some(100), + "re-provision reports the limit it replaced" + ); + } + + #[test] + fn remove_budget_truly_unprovisions_durably() { + // Council S28 F7: the provisioning rollback must be able to UNDO a first-time provision + // completely — afterwards the key is indistinguishable from never-provisioned (NoBudget, + // no snapshot), including across a restart. + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("spend_meter.json"); + { + let meter = SpendMeter::open_durable(path.clone()).unwrap(); + meter.set_budget("vm-ap-agent", 500).unwrap(); + assert!(meter.remove_budget("vm-ap-agent").unwrap(), "existed"); + assert!(!meter.remove_budget("vm-ap-agent").unwrap(), "idempotent"); + assert_eq!(meter.snapshot("vm-ap-agent"), None); + assert_eq!( + meter.try_debit("vm-ap-agent", 1).unwrap_err(), + SpendError::NoBudget + ); + } + let reopened = SpendMeter::open_durable(path).unwrap(); + assert_eq!( + reopened.snapshot("vm-ap-agent"), + None, + "the removal survives restart — no provisioned-at-zero artifact" + ); + // And a removal that cannot persist is ROLLED BACK — the budget (and its spend) stay. + let dir2 = tempfile::tempdir().unwrap(); + let sub = dir2.path().join("meter"); + std::fs::create_dir(&sub).unwrap(); + let meter = SpendMeter::open_durable(sub.join("spend_meter.json")).unwrap(); + meter.set_budget("vm-ap-agent", 500).unwrap(); + meter.try_debit("vm-ap-agent", 200).unwrap(); + std::fs::remove_dir_all(&sub).unwrap(); + assert_eq!( + meter.remove_budget("vm-ap-agent").unwrap_err(), + SpendError::Persist + ); + assert_eq!( + meter.remaining("vm-ap-agent"), + 300, + "the failed removal left the balance (limit AND spent) intact" + ); + } + + #[test] + fn post_publish_persist_failure_poisons_the_meter() { + // Council S28 F1 (closed S29): a persist that fails AFTER the rename published the new + // snapshot keeps memory in agreement with the visible disk and POISONS the meter — the + // payment is still refused, and every further mutation refuses until reopen. Reads project. + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("spend_meter.json"); + let meter = SpendMeter::open_durable(path.clone()).unwrap(); + meter.set_budget("vm-ap-agent", 500).unwrap(); + meter + .fail_parent_fsync + .store(true, std::sync::atomic::Ordering::SeqCst); + assert_eq!( + meter.try_debit("vm-ap-agent", 200).unwrap_err(), + SpendError::Poisoned, + "the payment is refused with the HONEST variant (S29 F1) — the debit IS in the \ + visible snapshot, so `Persist` (\"rolled back\") would be a lie" + ); + assert!(meter.is_poisoned()); + assert_eq!( + meter.remaining("vm-ap-agent"), + 300, + "memory keeps the published debit (it matches the visible disk) — no divergence" + ); + assert_eq!( + meter.try_debit("vm-ap-agent", 1).unwrap_err(), + SpendError::Poisoned, + "further mutations refuse fail-closed" + ); + assert_eq!( + meter.set_budget("vm-ap-agent", 900).unwrap_err(), + SpendError::Poisoned + ); + assert_eq!(meter.debit_saturating("vm-ap-agent", 5), 0); + assert!( + meter.snapshot("vm-ap-agent").is_some(), + "reads still project while poisoned" + ); + // Reopen from disk = the recovery path; the published debit is exactly what disk holds. + drop(meter); + let reopened = SpendMeter::open_durable(path).unwrap(); + assert!(!reopened.is_poisoned()); + assert_eq!(reopened.remaining("vm-ap-agent"), 300); + } + + #[test] + fn ensure_budget_post_publish_failure_reports_poisoned_not_persist() { + // The same S29 F1 honesty rule as set_budget/try_debit: a persist that fails AFTER the + // rename published the snapshot must not claim a rollback — the insert IS live in memory + // and on the visible disk, so the honest variant is `Poisoned`, never `Persist`. + let dir = tempfile::tempdir().unwrap(); + let meter = SpendMeter::open_durable(dir.path().join("spend_meter.json")).unwrap(); + meter + .fail_parent_fsync + .store(true, std::sync::atomic::Ordering::SeqCst); + assert_eq!( + meter.ensure_budget("vm-ap-agent", 500).unwrap_err(), + SpendError::Poisoned, + "the insert IS published — `Persist` (\"rolled back\") would be a lie" + ); + assert!(meter.is_poisoned()); + assert_eq!( + meter.remaining("vm-ap-agent"), + 500, + "memory keeps the published insert — it matches the visible disk" + ); + } + + #[test] + fn second_opener_of_one_snapshot_is_refused() { + // Council S28 F4: single-opener is enforced by the meter itself (exclusive flock held for + // its lifetime) — two live meters on one snapshot would last-writer-wins clobber `spent`. + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("spend_meter.json"); + let first = SpendMeter::open_durable(path.clone()).unwrap(); + assert!( + SpendMeter::open_durable(path.clone()).is_err(), + "a second opener fails fail-closed while the first is alive" + ); + drop(first); + assert!( + SpendMeter::open_durable(path).is_ok(), + "the lock releases with the meter" + ); + } + + #[test] + fn durable_meter_refuses_a_tampered_snapshot_shape() { + // Council S28 hardening: the writer never produces duplicate keys (it serializes a map), + // so a duplicate is tampering — last-write-wins would silently swap a balance. And a huge + // file is a forgery/corruption, not a balance set — bound it before parsing. + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("spend_meter.json"); + std::fs::write( + &path, + br#"{"version":1,"balances":[ + {"key":"vm-a","limit":10,"spent":10}, + {"key":"vm-a","limit":1000,"spent":0} + ]}"#, + ) + .unwrap(); + assert!( + SpendMeter::open_durable(path.clone()).is_err(), + "a duplicate key refuses to open" + ); + let mut huge = Vec::from(&b"{\"version\":1,\"balances\":["[..]); + huge.resize(4 * 1024 * 1024 + 1, b' '); + std::fs::write(&path, huge).unwrap(); + assert!( + SpendMeter::open_durable(path).is_err(), + "an oversized snapshot refuses to open" + ); + } } diff --git a/elastos/crates/elastos-runtime/src/primitives/time.rs b/elastos/crates/elastos-runtime/src/primitives/time.rs index f00a3cde..8c706b79 100644 --- a/elastos/crates/elastos-runtime/src/primitives/time.rs +++ b/elastos/crates/elastos-runtime/src/primitives/time.rs @@ -24,17 +24,33 @@ impl SecureTimeSource { Self { counter_path: None } } - /// Create a time source with persistence to the given path + /// Create a time source with persistence to the given path. + /// + /// RECOVERY SEMANTICS: an unreadable or unparseable counter file restarts the monotonic + /// counter from zero (loudly — a warning names the file), the same as a first run. Within one + /// process timestamps stay strictly monotonic either way; what a corrupt file costs is + /// CROSS-RESTART ordering against records stamped before the corruption. The audit chain does + /// not depend on that (its ordering is the hash chain's `seq`, not the timestamp counter). pub fn with_persistence(path: impl AsRef) -> std::io::Result { let path = path.as_ref().to_path_buf(); // Load existing counter if file exists if path.exists() { - if let Ok(content) = fs::read_to_string(&path) { - if let Ok(value) = content.trim().parse::() { + match fs::read_to_string(&path) { + Ok(content) => match content.trim().parse::() { // Start from saved value + 1 to ensure monotonicity - SecureTimestamp::init_counter(value + 1); - } + Ok(value) => SecureTimestamp::init_counter(value + 1), + Err(e) => tracing::warn!( + "monotonic counter file {} is unparseable ({e}) — restarting the \ + counter from zero (cross-restart ordering lost)", + path.display() + ), + }, + Err(e) => tracing::warn!( + "monotonic counter file {} is unreadable ({e}) — restarting the counter \ + from zero (cross-restart ordering lost)", + path.display() + ), } } diff --git a/elastos/crates/elastos-runtime/src/provider/bridge.rs b/elastos/crates/elastos-runtime/src/provider/bridge.rs index ceed6fd7..60ff734b 100755 --- a/elastos/crates/elastos-runtime/src/provider/bridge.rs +++ b/elastos/crates/elastos-runtime/src/provider/bridge.rs @@ -189,7 +189,15 @@ impl ProviderBridge { /// Starts the binary, sends Init with the given config, and waits /// for the init response. pub async fn spawn(binary_path: &Path, config: ProviderConfig) -> Result { - let mut child = Command::new(binary_path) + let mut cmd = Command::new(binary_path); + // P16 (Sprint 46, council red-team F1): provider capsules inherit the gateway env by + // default — strip the runtime-only secrets (rail bearer, broadcastable signed tx) so a + // compromised provider binary cannot read them from its own environment. ONE shared list — + // see `provider::RUNTIME_ONLY_SECRETS`. + for secret in super::RUNTIME_ONLY_SECRETS { + cmd.env_remove(secret); + } + let mut child = cmd .stdin(std::process::Stdio::piped()) .stdout(std::process::Stdio::piped()) .stderr(std::process::Stdio::inherit()) diff --git a/elastos/crates/elastos-runtime/src/provider/mod.rs b/elastos/crates/elastos-runtime/src/provider/mod.rs index 81663a2d..1d41e001 100755 --- a/elastos/crates/elastos-runtime/src/provider/mod.rs +++ b/elastos/crates/elastos-runtime/src/provider/mod.rs @@ -9,6 +9,26 @@ pub mod bridge; mod registry; +/// Runtime-only SECRETS a spawned capsule must never inherit (Sprint 46, council S43 guardian F4 + +/// S46 red-team F1 — P16). Both are consumed exclusively IN-PROCESS by the gateway and passed +/// onward as explicit op ARGUMENTS where needed, so no capsule has a legitimate use for the env +/// copy: +/// - `ELASTOS_DDRM_BUY_SIGNED_TX` — a fully broadcastable signed transaction (the external- +/// signature buy leg). Leaked to a hostile capsule binary it could be broadcast out-of-band. +/// - `ELASTOS_PAYMENT_TOKEN` — the HTTP payment rail's bearer token. A capsule holding it could +/// charge the rail directly. +/// +/// ONE list (P5), stripped at EVERY capsule spawn seam: `capsule_watchdog::spawn_grouped` +/// (chain/wallet/rights/content sidecars), [`ProviderBridge::spawn`](bridge::ProviderBridge) +/// (the general provider capsules), the carrier service spawn, and the shell-capsule spawns +/// (main/serve_cmd). Host-TOOL spawns (git, tar, the gateway self re-exec — which legitimately +/// needs its own env) are deliberately NOT stripped. A source-structural guard +/// (`capsule_watchdog::every_command_spawn_site_is_a_known_seam_and_capsule_seams_strip_secrets`) +/// pins every `Command::new` site in the tree onto one of those two classifications, so a new +/// spawn path cannot silently skip the strip. This is a targeted denylist of runtime-only +/// secrets, NOT a full per-capsule env allowlist — that remains the stronger tracked hardening. +pub const RUNTIME_ONLY_SECRETS: &[&str] = &["ELASTOS_DDRM_BUY_SIGNED_TX", "ELASTOS_PAYMENT_TOKEN"]; + pub use bridge::{CapsuleProvider, ProviderBridge, ProviderConfig as BridgeProviderConfig}; pub use registry::{ EntryType, Provider, ProviderByteRange, ProviderCarrierInvoker, ProviderCarrierRoute, diff --git a/elastos/crates/elastos-server/Cargo.toml b/elastos/crates/elastos-server/Cargo.toml index 50a026b1..170ded74 100644 --- a/elastos/crates/elastos-server/Cargo.toml +++ b/elastos/crates/elastos-server/Cargo.toml @@ -120,3 +120,12 @@ default = [] # startup guard refuses to boot in a dev rights mode. Dev/CI build the gateway with # `--features dev-modes` to use Dev/ChainMock rights + the local quorum. dev-modes = [] +# live-chain: compile the OPERATOR/CI live testnet-buy integration test +# (`tests/live_drm_buy.rs`), which drives the REAL `ChainDrmMarketplace` against env-configured +# endpoints per docs/LIVE_BUY_RUNBOOK.md. OFF by default and NEVER in the default gate — it needs +# a funded wallet, a live RPC, and a deployed listing, none of which a CI sandbox has. The test is +# additionally `#[ignore]`d, so even `--features live-chain` runs it only when named explicitly: +# `cargo test -p elastos-server --features live-chain --test live_drm_buy -- --ignored`. +# SAFETY: this pulls in `dev-modes` (managed self-signing) — NEVER reuse a `--features live-chain` +# build as a release artifact; build release with default features only. +live-chain = ["dev-modes"] diff --git a/elastos/crates/elastos-server/src/agent_store.rs b/elastos/crates/elastos-server/src/agent_store.rs new file mode 100644 index 00000000..f8f3dba7 --- /dev/null +++ b/elastos/crates/elastos-server/src/agent_store.rs @@ -0,0 +1,279 @@ +//! Mandate-scoped durable agent state — the store behind the `runtime.state_put` affordance. +//! +//! The second SIDE-EFFECTING mandate affordance (Sprint 17). Where `runtime.notify` writes a +//! one-shot row into the operator's Inbox, this is durable, mutable, READABLE-BACK state an agent +//! maintains under a mandate: a key → commitment entry, last-write-wins, every write attributed to +//! the mandate + intent that authorized it. It is the honest generalization of the side-effecting +//! pattern to real data — and it stays honest by carrying only the SIGNED declaration's own fields +//! (there is no free-text payload channel; the value an agent commits to is its `input_hash`, the +//! same commitment the mandate receipt already binds), so nothing an agent writes here can smuggle +//! content the intent signature does not cover (the council-F1 lesson from `runtime.notify`). +//! +//! PRINCIPAL-SCOPED: an entry's identity is `(capsule, key)`, so one agent can never read or +//! overwrite another agent's key — the acting `capsule` is gate-bound to the mandate, so this is +//! the same principal-scoping `content_seen` uses, not a spoofable string. + +use std::fs; +use std::path::{Path, PathBuf}; +use std::time::{SystemTime, UNIX_EPOCH}; + +use anyhow::Context; +use elastos_common::localhost::rooted_localhost_fs_path; +use serde::{Deserialize, Serialize}; + +const AGENT_STATE_SCHEMA: &str = "elastos.agent-state/v1"; +const AGENT_STATE_ROOT_URI: &str = "localhost://Local/Shared/System/AgentState"; +const AGENT_STATE_FILE: &str = "agent_state.json"; + +/// A cap on the number of distinct keys ONE agent (capsule) may hold, so an agent flooding +/// distinct keys under a mandate cannot grow the store without bound (the council-F1 flood lesson). +/// Newest-written keys are kept. Generous — real agent state is a handful of cursors/flags. +const MAX_KEYS_PER_CAPSULE: usize = 256; + +/// One durable agent-state entry: a key an agent wrote under a mandate, and the commitment it made. +/// Every field is either gate-bound (`capsule`, `grant_id`) or lifted verbatim from the signed +/// declaration (`key`, `input_hash`, `intent_id`) — never free-form operator/attacker text. +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +pub struct AgentStateEntry { + /// The acting capsule (principal) that owns this key. + pub capsule: String, + /// The state key (a slug, ≤64 chars of [A-Za-z0-9._-]). + pub key: String, + /// The value the agent COMMITTED to — the declaration's `input_hash` (hex, or empty). This is a + /// commitment, not a payload: the intent declaration carries no bytes, only their hash, so the + /// store records exactly what the mandate receipt also binds. + pub value_hash: String, + /// The mandate (standing-grant / token id) that authorized the write. + pub grant_id: String, + /// The intent that performed this specific write. + pub intent_id: String, + /// Unix seconds when the write landed. + pub written_at: u64, + /// Monotonic per-key version, incremented on each overwrite (a durable, attributed history + /// depth without keeping every revision). + pub version: u64, +} + +#[derive(Debug, Clone, Serialize, Deserialize, Default)] +struct AgentStateStore { + #[serde(default)] + schema: String, + #[serde(default)] + entries: Vec, +} + +fn agent_state_path(data_dir: &Path) -> anyhow::Result { + let root = rooted_localhost_fs_path(data_dir, AGENT_STATE_ROOT_URI) + .context("failed to resolve agent-state root")?; + Ok(root.join(AGENT_STATE_FILE)) +} + +fn read_store(path: &Path) -> anyhow::Result { + if !path.exists() { + return Ok(AgentStateStore::default()); + } + let bytes = fs::read(path).with_context(|| format!("failed to read {}", path.display()))?; + if bytes.is_empty() { + return Ok(AgentStateStore::default()); + } + serde_json::from_slice(&bytes).with_context(|| format!("invalid {}", path.display())) +} + +fn write_store_atomic(path: &Path, store: &AgentStateStore) -> anyhow::Result<()> { + let parent = path + .parent() + .ok_or_else(|| anyhow::anyhow!("agent-state path missing parent"))?; + fs::create_dir_all(parent)?; + let tmp = parent.join(format!(".{AGENT_STATE_FILE}.tmp")); + let json = serde_json::to_vec_pretty(store)?; + fs::write(&tmp, &json)?; + fs::rename(&tmp, path)?; + Ok(()) +} + +/// Write (or overwrite, last-write-wins) an agent-state key, PRINCIPAL-SCOPED to `capsule`. Returns +/// the landed entry's version. Fail-closed on I/O: a write that cannot be persisted returns Err (⇒ +/// the `runtime.state_put` executor Declines, never a claimed write). Overwriting an existing +/// `(capsule, key)` increments its version; a new key past the per-capsule cap evicts the +/// oldest-written key of THAT capsule (never another capsule's). +pub fn put_agent_state( + data_dir: &Path, + capsule: &str, + key: &str, + value_hash: &str, + grant_id: &str, + intent_id: &str, +) -> anyhow::Result { + let path = agent_state_path(data_dir)?; + let mut store = read_store(&path)?; + if store.schema.trim().is_empty() { + store.schema = AGENT_STATE_SCHEMA.to_string(); + } + let written_at = SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_secs()) + .unwrap_or(0); + + let version = if let Some(existing) = store + .entries + .iter_mut() + .find(|e| e.capsule == capsule && e.key == key) + { + // Overwrite in place — last-write-wins, version deepens the attributed history. + existing.value_hash = value_hash.to_string(); + existing.grant_id = grant_id.to_string(); + existing.intent_id = intent_id.to_string(); + existing.written_at = written_at; + existing.version = existing.version.saturating_add(1); + existing.version + } else { + store.entries.push(AgentStateEntry { + capsule: capsule.to_string(), + key: key.to_string(), + value_hash: value_hash.to_string(), + grant_id: grant_id.to_string(), + intent_id: intent_id.to_string(), + written_at, + version: 1, + }); + // Enforce the per-capsule key cap — evict the oldest-written keys of THIS capsule only, and + // NEVER the key we just wrote (else `put` would return Ok for a key that is not in the + // persisted store — a Performed-without-effect honesty break; `written_at` is coarse + // seconds, so a burst could otherwise tie the new key with evictees). Oldest-first by + // (written_at, then version) with the just-written (capsule,key) explicitly excluded. + let mut candidates: Vec<(usize, u64, u64)> = store + .entries + .iter() + .enumerate() + .filter(|(_, e)| e.capsule == capsule && e.key != key) + .map(|(i, e)| (i, e.written_at, e.version)) + .collect(); + // +1 because the just-written key is excluded from candidates but counts toward the cap. + if candidates.len() + 1 > MAX_KEYS_PER_CAPSULE { + candidates.sort_by_key(|(_, ts, ver)| (*ts, *ver)); + let drop = candidates.len() + 1 - MAX_KEYS_PER_CAPSULE; + let drop_idx: std::collections::HashSet = + candidates.iter().take(drop).map(|(i, _, _)| *i).collect(); + let mut i = 0; + store.entries.retain(|_| { + let keep = !drop_idx.contains(&i); + i += 1; + keep + }); + } + 1 + }; + + write_store_atomic(&path, &store)?; + Ok(version) +} + +/// Read back an agent-state key, PRINCIPAL-SCOPED: only `capsule`'s own key is returned. A missing +/// key (or a different capsule's key) is `None` — never another principal's state. This is the +/// AGENT-facing read (one principal, its own key); an agent must never reach across principals. +pub fn get_agent_state( + data_dir: &Path, + capsule: &str, + key: &str, +) -> anyhow::Result> { + let path = agent_state_path(data_dir)?; + let store = read_store(&path)?; + Ok(store + .entries + .into_iter() + .find(|e| e.capsule == capsule && e.key == key)) +} + +/// Every agent-state entry, sorted by `(capsule, key)` — the OPERATOR-facing read. This deliberately +/// spans ALL principals because the caller is the operator/shell (the runtime's grant root, gated by +/// the home-launch token), the same trust level that already sees every mandate. It is NOT an agent +/// path: no agent reaches this — the per-principal isolation (`get_agent_state`) is what protects +/// agents from each other; the operator, who owns the runtime, sees the whole picture. +pub fn list_agent_state(data_dir: &Path) -> anyhow::Result> { + let path = agent_state_path(data_dir)?; + let mut entries = read_store(&path)?.entries; + entries.sort_by(|a, b| a.capsule.cmp(&b.capsule).then(a.key.cmp(&b.key))); + Ok(entries) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn put_then_get_is_principal_scoped_and_versions_on_overwrite() { + let dir = tempfile::tempdir().unwrap(); + let d = dir.path(); + // Agent A writes a key. + let v1 = put_agent_state(d, "vm-a", "cursor", "cafe01", "grant-a", "i1").unwrap(); + assert_eq!(v1, 1); + let got = get_agent_state(d, "vm-a", "cursor").unwrap().unwrap(); + assert_eq!(got.value_hash, "cafe01"); + assert_eq!(got.version, 1); + assert_eq!(got.grant_id, "grant-a"); + + // Overwrite deepens the version, last-write-wins. + let v2 = put_agent_state(d, "vm-a", "cursor", "beef02", "grant-a", "i2").unwrap(); + assert_eq!(v2, 2); + let got = get_agent_state(d, "vm-a", "cursor").unwrap().unwrap(); + assert_eq!(got.value_hash, "beef02"); + assert_eq!(got.version, 2); + assert_eq!(got.intent_id, "i2"); + + // PRINCIPAL-SCOPED: agent B cannot see A's key, and its own same-named key is independent. + assert!(get_agent_state(d, "vm-b", "cursor").unwrap().is_none()); + put_agent_state(d, "vm-b", "cursor", "d00d03", "grant-b", "i3").unwrap(); + assert_eq!( + get_agent_state(d, "vm-b", "cursor") + .unwrap() + .unwrap() + .value_hash, + "d00d03" + ); + // A's key is untouched by B's write. + assert_eq!( + get_agent_state(d, "vm-a", "cursor") + .unwrap() + .unwrap() + .value_hash, + "beef02" + ); + } + + #[test] + fn per_capsule_key_cap_evicts_only_that_capsule() { + let dir = tempfile::tempdir().unwrap(); + let d = dir.path(); + // One durable key for capsule B that must SURVIVE A's flood. + put_agent_state(d, "vm-b", "keep", "b0", "g", "ib").unwrap(); + for i in 0..(MAX_KEYS_PER_CAPSULE + 50) { + put_agent_state(d, "vm-a", &format!("k{i}"), "aa", "g", &format!("i{i}")).unwrap(); + } + let store = read_store(&agent_state_path(d).unwrap()).unwrap(); + let a_keys = store.entries.iter().filter(|e| e.capsule == "vm-a").count(); + assert!( + a_keys <= MAX_KEYS_PER_CAPSULE, + "A capped at {MAX_KEYS_PER_CAPSULE}, got {a_keys}" + ); + // The operator-facing list spans all principals (sorted), unlike the per-agent read. + let all = list_agent_state(d).unwrap(); + assert!(all.iter().any(|e| e.capsule == "vm-b" && e.key == "keep")); + assert!(all.iter().any(|e| e.capsule == "vm-a")); + assert!( + all.windows(2) + .all(|w| (w[0].capsule.as_str(), w[0].key.as_str()) + <= (w[1].capsule.as_str(), w[1].key.as_str())), + "sorted by (capsule, key)" + ); + // B's key is never evicted by A's flood. + assert!(get_agent_state(d, "vm-b", "keep").unwrap().is_some()); + // The LAST key written is always readable back — the cap never evicts the just-written key + // (would be a Performed-without-effect break). Coarse-second timestamps mean the whole + // flood shares written_at, so this is the real same-second-tie guard. + let last_key = format!("k{}", MAX_KEYS_PER_CAPSULE + 50 - 1); + assert!( + get_agent_state(d, "vm-a", &last_key).unwrap().is_some(), + "the most recently written key must survive its own cap eviction" + ); + } +} diff --git a/elastos/crates/elastos-server/src/api/access_grant.rs b/elastos/crates/elastos-server/src/api/access_grant.rs index 9cfc55fd..aba3df17 100644 --- a/elastos/crates/elastos-server/src/api/access_grant.rs +++ b/elastos/crates/elastos-server/src/api/access_grant.rs @@ -118,15 +118,22 @@ fn run_sidecar(mode: &str, input: &Value) -> Result { "grant sidecar not found at {bin}; build scripts/dev/ddrm-media-authority or set ELASTOS_DDRM_MEDIA_AUTHORITY_BIN" )); } - let mut child = Command::new(&bin) - .arg(mode) + let mut cmd = Command::new(&bin); + cmd.arg(mode) .stdin(Stdio::piped()) .stdout(Stdio::piped()) - .stderr(Stdio::inherit()) - .spawn() - .map_err(|e| format!("spawn grant sidecar ({bin} {mode}): {e}"))?; + .stderr(Stdio::inherit()); + // Guard the child so EVERY early return reaps it — including the stdin-write path a sidecar + // that exits immediately forces to EPIPE (council S42 red-team F2). `ReapGuard::drop` reaps via + // the bounded `reap_grouped`, so no path leaks a zombie. + let mut guard = crate::api::capsule_watchdog::ReapGuard::new( + crate::api::capsule_watchdog::spawn_grouped(&mut cmd) + .map_err(|e| format!("spawn grant sidecar ({bin} {mode}): {e}"))?, + ); { - let mut stdin = child.stdin.take().ok_or("no stdin")?; + let mut stdin = guard.child_mut().stdin.take().ok_or("no stdin")?; + // The stdin WRITE is not watchdog-bounded, but the payload is a single small JSON object + // far below the OS pipe buffer, so the kernel accepts it without blocking on the child. stdin .write_all( serde_json::to_vec(input) @@ -136,14 +143,18 @@ fn run_sidecar(mode: &str, input: &Value) -> Result { .map_err(|e| format!("write sidecar stdin: {e}"))?; // stdin dropped here -> EOF, so the sidecar's read_to_string returns. } - let out = child - .wait_with_output() - .map_err(|e| format!("wait sidecar: {e}"))?; - if !out.status.success() { - return Err(format!("grant sidecar {mode} exited with {}", out.status)); - } - let line = String::from_utf8_lossy(&out.stdout); - serde_json::from_str(line.trim()).map_err(|e| format!("parse sidecar output: {e}: {line}")) + // Hand the (single-use) child to the shared one-shot reader, which OWNS the arm → read-to-EOF → + // disarm → reap ordering + the length cap + the fire marker (council S42 guardian F3 — no + // hand-rolled fourth copy). The `guard` has already covered every pre-read error path (spawn, + // stdin take/write, stdout take); `disarm()` transfers the child to the reader for the reap. + let stdout = std::io::BufReader::new(guard.child_mut().stdout.take().ok_or("no stdout")?); + let mut child = guard.disarm(); + let out = crate::api::capsule_watchdog::read_to_eof_deadlined( + &mut child, + stdout, + &format!("grant sidecar {mode}"), + )?; + serde_json::from_str(out.trim()).map_err(|e| format!("parse sidecar output: {e}: {out}")) } /// What `prepare` hands back to the browser. @@ -430,3 +441,54 @@ mod attempt_tests { assert_eq!(g, None); } } + +#[cfg(test)] +mod deadline_tests { + use super::*; + + /// Sprint 42 ratchet: a HUNG grant sidecar is killed at the deadline — `prepare` (the + /// trustless-open grant assembly) returns BOUNDED (never parks the open thread for the child's + /// lifetime) and the open fails CLOSED (no grant assembled). The grant sidecar is on the OPEN + /// path, so a timeout is a fail-closed refusal, never a money decision. + #[test] + #[cfg(unix)] + fn a_hung_grant_sidecar_is_killed_and_the_open_fails_closed() { + let _g = crate::api::ddrm_env_lock(); + let prior_deadline = std::env::var("ELASTOS_CHAIN_READ_DEADLINE_SECS").ok(); + let prior_bin = std::env::var("ELASTOS_DDRM_MEDIA_AUTHORITY_BIN").ok(); + std::env::set_var("ELASTOS_CHAIN_READ_DEADLINE_SECS", "1"); + + let dir = tempfile::tempdir().unwrap(); + let stub = dir.path().join("hung-grant-sidecar.sh"); + std::fs::write(&stub, "#!/bin/sh\nsleep 300\n").unwrap(); + use std::os::unix::fs::PermissionsExt as _; + std::fs::set_permissions(&stub, std::fs::Permissions::from_mode(0o755)).unwrap(); + std::env::set_var("ELASTOS_DDRM_MEDIA_AUTHORITY_BIN", &stub); + + let started = std::time::Instant::now(); + let err = match prepare(8453, "abcd", "bm9kZXNldA==", "0xtestowner") { + Ok(_) => panic!("expected the hung grant sidecar to be killed, not a prepared grant"), + Err(e) => e, + }; + + match prior_deadline { + Some(v) => std::env::set_var("ELASTOS_CHAIN_READ_DEADLINE_SECS", v), + None => std::env::remove_var("ELASTOS_CHAIN_READ_DEADLINE_SECS"), + } + match prior_bin { + Some(v) => std::env::set_var("ELASTOS_DDRM_MEDIA_AUTHORITY_BIN", v), + None => std::env::remove_var("ELASTOS_DDRM_MEDIA_AUTHORITY_BIN"), + } + + assert!( + started.elapsed() < std::time::Duration::from_secs(15), + "the grant assembly is BOUNDED by the deadline, not the child's 300s sleep" + ); + assert!( + err.contains(crate::api::capsule_watchdog::ACCESS_DEADLINE_MARKER) + && err.contains("DENIED"), + "a hung grant sidecar fails the open CLOSED at the deadline, carrying the shared \ + access marker: {err}" + ); + } +} diff --git a/elastos/crates/elastos-server/src/api/browser_capsules.rs b/elastos/crates/elastos-server/src/api/browser_capsules.rs index d6bcf274..5ed8788f 100644 --- a/elastos/crates/elastos-server/src/api/browser_capsules.rs +++ b/elastos/crates/elastos-server/src/api/browser_capsules.rs @@ -515,6 +515,32 @@ mod tests { assert_eq!(response.status(), StatusCode::NOT_FOUND); } + #[test] + fn mandates_ships_as_a_launchable_browser_app() { + // The Mandates app ships as a dev capsule at repo `capsules/mandates`. It must be discovered + // as a SHELL-LAUNCHABLE browser (html) app so the Home launcher lists it and opens it in a + // window like any other app — the native "opens in the shell" contract this sprint delivers. + let data_dir = tempfile::tempdir().unwrap(); + let launchable = list_launchable_browser_capsules(data_dir.path()); + let mandates = launchable + .iter() + .find(|capsule| capsule.name == "mandates") + .expect("mandates capsule is launchable from the dev root"); + assert!( + mandates.role.is_shell_launchable(), + "role must be shell-launchable" + ); + // It resolves + serves as a data/html browser capsule (the dashboard renders in the window). + let cap = resolve_browser_capsule(data_dir.path(), "mandates") + .expect("mandates resolves as a browser capsule"); + assert_eq!(cap.manifest.capsule_type, CapsuleType::Data); + assert!(cap.entrypoint.ends_with(".html")); + assert!( + cap.root.join(&cap.entrypoint).is_file(), + "the dashboard html is served" + ); + } + #[test] fn list_launchable_browser_capsules_prefers_installed_metadata() { let data_dir = tempfile::tempdir().unwrap(); diff --git a/elastos/crates/elastos-server/src/api/buy_authority.rs b/elastos/crates/elastos-server/src/api/buy_authority.rs index dfc5393f..1308b4a1 100644 --- a/elastos/crates/elastos-server/src/api/buy_authority.rs +++ b/elastos/crates/elastos-server/src/api/buy_authority.rs @@ -53,6 +53,66 @@ pub struct BuyOutcome { pub unsigned_tx: Value, } +/// The outcome-class of a `buy_access` failure, decided BY CONSTRUCTION — which code path produced +/// it — NOT by sniffing the error string (Sprint 43, retiring `is_pre_broadcast_refusal`). This is +/// what makes the DRM rail's refund-vs-hold decision immune to a HOSTILE provider's error text: a +/// broadcast-op failure can ONLY be built as [`Indeterminate`](BuyError::Indeterminate) at its +/// single call site (`broadcast_signed_*`/`broadcast_mock`), so no message content — not even a +/// string that embeds a pre-broadcast sentinel — can turn a sent tx into a refund. The one +/// unbreakable invariant (never refund a tx that may have landed) is now a TYPE property, not a +/// substring match. +#[derive(Debug)] +pub enum BuyError { + /// The failure occurred strictly BEFORE any broadcast op ran — wallet-not-linked, + /// resolve/source/sold-out/drift, the wallet SIGN leg, the chain PREPARE (read) leg, or a + /// missing external signature. The tx was never sent, so the DRM rail may refund (NotCharged). + /// "Never sent" is provable modulo the TRUSTED-CORE assumption that the operator-pinned + /// `chain-provider`/`wallet-provider` binaries do not self-broadcast (the runtime owns the only + /// `broadcast_signed_*` call, and a release build never even reaches the managed-sign leg — + /// `wallet_signing()` is `false`); an env allowlist for spawned capsules is the P16 hardening + /// that would make it provable without the trust assumption (tracked, KNOWN_GAPS). + PreBroadcast(String), + /// The failure occurred AT or AFTER the broadcast op (`eth_sendRawTransaction`), or anywhere + /// its send status cannot be proven un-sent. The tx MAY have landed, so the DRM rail KEEPS the + /// reservation (Indeterminate) — never a refund. + Indeterminate(String), +} + +impl BuyError { + /// The human-readable message, variant-independent — for HTTP/audit surfaces that only need + /// the text (the money classification is the variant, read separately). + pub fn message(&self) -> &str { + match self { + BuyError::PreBroadcast(m) | BuyError::Indeterminate(m) => m, + } + } +} + +impl std::fmt::Display for BuyError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(self.message()) + } +} + +impl std::error::Error for BuyError {} + +/// Fail-closed refusal message text the buy path produces when it PROVABLY never sent a +/// transaction. Since Sprint 43 these are NO LONGER money-classification-bearing (the DRM rail +/// classifies by the [`BuyError`] VARIANT, not by matching these strings) — they are the +/// user-facing message carried inside a [`BuyError::PreBroadcast`], and a couple are still matched +/// by HTTP surfaces (`viewer_open`) to pick a status code. Kept as shared consts so producers and +/// those surface checks cannot drift. +pub(crate) const ERR_WALLET_NOT_LINKED: &str = + "wallet not linked: a buy needs the principal's EVM address"; +/// Suffix shared by every fail-closed abort before broadcast (sold-out, no-active-listing, +/// listing-drift). [`ERR_SOLD_OUT`] must keep ending with this — a test pins it. +pub(crate) const ERR_BUY_ABORTED_SUFFIX: &str = "buy aborted (fail closed)"; +/// The abort-on-drift guard's refusal when no operative resolved before assembly. +pub(crate) const ERR_NONE_RESOLVED_SUFFIX: &str = "none resolved — fail closed"; +/// The sold-out refusal, shared by the buy and the read-only quote. +pub(crate) const ERR_SOLD_OUT: &str = + "listing sold out (on-chain supply 0) — buy aborted (fail closed)"; + /// Real Base AuthorityGateway — `buyAccess` is sent here (from `~/.pc2` `wallet.js` / /// `abis.ts`), NOT to the operative directly. Default `to` for the buy; overridable. const BASE_AUTHORITY_GATEWAY: &str = "0x09dBe796f40ECEffEAccf243c3d758C4c1d8D87D"; @@ -89,7 +149,7 @@ fn wallet_signing() -> bool { } /// The EVM chain id for the buy (default Base mainnet); overridable for other deployments. -fn chain_id_default() -> u64 { +pub(crate) fn chain_id_default() -> u64 { env_nonempty("ELASTOS_DDRM_CHAIN_ID") .and_then(|s| s.parse().ok()) .unwrap_or(8453) @@ -121,7 +181,7 @@ pub fn buy_access( subject: &str, now_unix: u64, target: &BuyTarget, -) -> Result { +) -> Result { let mode = super::rights_authority::rights_mode(); // Chain modes are keyed on a real wallet — fail closed without one (same rule the @@ -132,14 +192,16 @@ pub fn buy_access( && subject.trim().is_empty() && !wallet_signing() { - return Err("wallet not linked: a buy needs the principal's EVM address".to_string()); + return Err(BuyError::PreBroadcast(ERR_WALLET_NOT_LINKED.to_string())); } let unsigned_tx = assemble_buy_tx(content_id, subject, None); match mode { RightsMode::Dev => { - super::owned_ledger::record(content_id, &dev_subject(principal_id, subject))?; + // Dev never broadcasts (synthetic hash, local ledger) — any failure is pre-broadcast. + super::owned_ledger::record(content_id, &dev_subject(principal_id, subject)) + .map_err(BuyError::PreBroadcast)?; Ok(BuyOutcome { tx_hash: synthetic_hash(content_id, subject, now_unix), owned_now: true, @@ -156,6 +218,8 @@ pub fn buy_access( // authoritative buyer, so ownership is recorded under its address. let chain_id = chain_id_default(); let mut intent_seen = Value::Null; + // The SIGN leg runs strictly BEFORE broadcast — a failure here (incl. a wallet + // deadline) proves the tx was never sent ⇒ pre-broadcast refund. let sig = super::wallet_signer::sign_with_managed_account( principal_id, chain_id, @@ -164,10 +228,16 @@ pub fn buy_access( intent_seen = intent.clone(); Ok(intent) }, - )?; + ) + .map_err(BuyError::PreBroadcast)?; + // Broadcast op and everything after it is post-broadcast — the tx MAY be out, so a + // failure is Indeterminate regardless of the provider's message (the hostile-text + // immunity is this call site's typing, not a string match). let tx_hash = - super::chain_tx::broadcast_signed_mock(&intent_seen, &sig.signed_transaction)?; - super::owned_ledger::record(content_id, &sig.signer)?; + super::chain_tx::broadcast_signed_mock(&intent_seen, &sig.signed_transaction) + .map_err(BuyError::Indeterminate)?; + super::owned_ledger::record(content_id, &sig.signer) + .map_err(BuyError::Indeterminate)?; return Ok(BuyOutcome { tx_hash, owned_now: true, @@ -176,11 +246,12 @@ pub fn buy_access( }); } // Run the REAL chain-provider broadcast op against an in-process RPC mock that - // returns a canned tx hash, so the production broadcast path is exercised. - let tx_hash = broadcast_mock(&unsigned_tx)?; + // returns a canned tx hash, so the production broadcast path is exercised. The op and + // everything after are post-broadcast ⇒ Indeterminate on failure. + let tx_hash = broadcast_mock(&unsigned_tx).map_err(BuyError::Indeterminate)?; // The mock chain has no token state, so record the purchase in the ledger the // chain-mock rights read (`ELASTOS_DDRM_CHAIN_ACCESS=ledger`) consults. - super::owned_ledger::record(content_id, subject)?; + super::owned_ledger::record(content_id, subject).map_err(BuyError::Indeterminate)?; Ok(BuyOutcome { tx_hash, owned_now: true, @@ -194,16 +265,16 @@ pub fn buy_access( // seller/price/payToken LIVE from sellersOf/listings (id=1). No ELASTOS_DDRM_BUY_* pins // required; env still overrides for dev. Fails closed on a missing channel, an unresolved // tokenId, or no active listing. The CEK path is untouched (P15). - let sourced = source_buy_terms(content_id, target)?; + // All of source/sold-out/drift are READ-ONLY, strictly before any broadcast ⇒ + // pre-broadcast refusals. + let sourced = source_buy_terms(content_id, target).map_err(BuyError::PreBroadcast)?; if sourced.supply == 0 { - return Err( - "listing sold out (on-chain supply 0) — buy aborted (fail closed)".to_string(), - ); + return Err(BuyError::PreBroadcast(ERR_SOLD_OUT.to_string())); } // Abort-on-drift (P11): if the buyer agreed to a price/pay-token in the UI, the live re-read // MUST match — else fail closed (the listing changed under them). if let Some(expected) = sourced.expected.as_ref() { - ensure_no_drift(expected, &sourced.live)?; + ensure_no_drift(expected, &sourced.live).map_err(BuyError::PreBroadcast)?; } let unsigned = assemble_buy_tx_core(content_id, subject, &sourced.terms); if wallet_signing() { @@ -212,6 +283,12 @@ pub fn buy_access( // the signed bytes through the REAL chain-provider — the seam that makes `chain` live. let chain_id = chain_id_default(); let mut intent_seen = Value::Null; + // SIGN leg (incl. the chain PREPARE read inside the closure) runs strictly BEFORE + // broadcast ⇒ a failure here is pre-broadcast (the tx was never sent). NOTE this is + // STRICTLY MORE PRECISE than the old string classifier: a chain deadline on the + // PREPARE (read) leg is now correctly a refund, while the same marker on the SEND + // leg below stays Indeterminate — a distinction the string could not make, because + // classification is now the CALL SITE, not the message. let sig = super::wallet_signer::sign_with_managed_account( principal_id, chain_id, @@ -220,8 +297,10 @@ pub fn buy_access( intent_seen = intent.clone(); Ok(intent) }, - )?; - let tx_hash = super::chain_tx::broadcast_signed_live(&sig.signed_transaction)?; + ) + .map_err(BuyError::PreBroadcast)?; + let tx_hash = super::chain_tx::broadcast_signed_live(&sig.signed_transaction) + .map_err(BuyError::Indeterminate)?; // Ownership is read back from `hasAccessByContentId` once the tx confirms, // not from the local ledger; owned_now reflects "broadcast accepted". return Ok(BuyOutcome { @@ -234,14 +313,16 @@ pub fn buy_access( // Real chain, no runtime signing: broadcast an externally-signed tx if provided, else hand // back the live-assembled unsigned tx for the user's external wallet (the release path). let Some(signed) = env_nonempty("ELASTOS_DDRM_BUY_SIGNED_TX") else { - return Err(format!( + // No signature yet ⇒ nothing was broadcast (a precondition, pre-broadcast refund). + return Err(BuyError::PreBroadcast(format!( "live buy needs a signature: either opt into runtime signing with \ ELASTOS_DDRM_BUY_SIGN=wallet (the wallet capsule signs with a managed \ key), or sign this assembled tx externally and resubmit via \ ELASTOS_DDRM_BUY_SIGNED_TX. unsigned_tx={unsigned}" - )); + ))); }; - let tx_hash = super::chain_tx::broadcast_signed_live(&signed)?; + let tx_hash = + super::chain_tx::broadcast_signed_live(&signed).map_err(BuyError::Indeterminate)?; // On real chain, ownership is read back from `hasAccessByContentId` once the // tx confirms — NOT from the local ledger. owned_now reflects "broadcast // accepted", not "confirmed"; the open re-reads the chain. @@ -255,6 +336,49 @@ pub fn buy_access( } } +/// The on-chain price + pay-token of a DRM listing, READ-ONLY (Sprint 36 — the price gate). The +/// price is the pay-token's smallest-unit amount as a decimal string (e.g. USDC 6-decimals); +/// `pay_token` is the ERC-20 address, or `"native"` for a zero-address (ETH) listing. Sourced +/// WITHOUT broadcasting so the pay gate can compare the mandate's cap against the real cost before +/// any money moves. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct BuyQuote { + pub price: String, + pub pay_token: String, + pub supply: u128, +} + +/// Read-only quote of what `buy_access` WOULD charge for `content_id`, without broadcasting +/// (Sprint 36). On the `chain` path it live-sources the lowest active listing's price + pay-token +/// via [`source_buy_terms`] (fail-closed on no listing / sold out); on dev/chain-mock there is no +/// real listing, so it returns a FREE quote (`price = "0"`, native) — the price gate is a no-op in +/// those insecure modes, which already require the explicit mock opt-in to wire the DRM rail. +pub fn quote_buy(content_id: &str, target: &BuyTarget) -> Result { + match super::rights_authority::rights_mode() { + RightsMode::Chain => { + let sourced = source_buy_terms(content_id, target)?; + if sourced.supply == 0 { + return Err(ERR_SOLD_OUT.to_string()); + } + // Return the RAW on-chain pay_token (a zero address for a native listing), NOT a + // display alias — the DRM settler binds it as the buy's expected_pay_token so + // abort-on-drift can cross-check a pay-token flip between quote and broadcast (council + // S36 red-team F2); a mapped "native" would mismatch the re-read zero address. + Ok(BuyQuote { + price: sourced.live.price, + pay_token: sourced.live.pay_token, + supply: sourced.supply, + }) + } + // Dev / ChainMock have no real listing to price — a FREE quote (the gate always passes). + _ => Ok(BuyQuote { + price: "0".to_string(), + pay_token: "native".to_string(), + supply: 1, + }), + } +} + /// The zero EVM address (a native/ETH listing's `payToken`). const ZERO_ADDR: &str = "0x0000000000000000000000000000000000000000"; /// Cap the live seller scan when sourcing the lowest active listing (bounded RPC fan-out). @@ -344,10 +468,9 @@ fn source_buy_terms(content_id: &str, target: &BuyTarget) -> Result String { hex::encode(Sha256::digest(id.as_bytes())) } -/// Left-pad a 20-byte EVM address to a 32-byte word. Tolerates a missing `0x` / short -/// input by hashing (demo calldata is never sent to a real contract in mock/dev). +/// Left-pad a 20-byte EVM address to a 32-byte word. This encoder IS on the live buy path +/// (`assemble_buy_tx_core` runs on `RightsMode::Chain`); the hash fallback for a malformed +/// address exists for dev/mock fixtures and is unreachable live, where every address is either +/// sourced from the chain read itself or validated upstream (a live buy with a hashed +/// address-word would fail on-chain, not silently misroute — the gateway checks its operands). fn word_from_address(addr: &str) -> String { let clean = addr.trim().trim_start_matches("0x"); if clean.len() == 40 && clean.bytes().all(|b| b.is_ascii_hexdigit()) { @@ -649,7 +775,10 @@ fn word_from_address(addr: &str) -> String { } } -/// A decimal `uint` as a 32-byte word (saturates absurd inputs; demo encoding only). +/// A decimal `uint` as a 32-byte word. Live-path caveat as [`word_from_address`]: the `1` +/// fallback for an unparseable decimal (quantity semantics — "one unit", never zero/free) is +/// only reachable from dev/fixture inputs; live quantities and prices are sourced on-chain and +/// re-checked by abort-on-drift before broadcast. fn word_from_uint(dec: &str) -> String { let n: u128 = dec.trim().parse().unwrap_or(1); format!("{n:064x}") @@ -725,7 +854,7 @@ pub(crate) fn ensure_no_drift(bound: &BoundTerms, reread: &BoundTerms) -> Result for (field, a, b) in checks { if !a.trim().eq_ignore_ascii_case(b.trim()) { return Err(format!( - "listing drift on {field}: bound {a:?} != re-read {b:?} — buy aborted (fail closed)" + "listing drift on {field}: bound {a:?} != re-read {b:?} — {ERR_BUY_ABORTED_SUFFIX}" )); } } @@ -843,6 +972,17 @@ mod tests { const SUBJECT: &str = "0x00000000000000000000000000000000000000bb"; + /// Since Sprint 43 the refusal consts are message text, NOT classifier anchors (the DRM rail + /// classifies by the `BuyError` variant, not by matching these). This just pins the internal + /// message-shape relationship so the two sold-out phrasings stay consistent for users. + #[test] + fn the_sold_out_refusal_keeps_the_shared_abort_suffix() { + assert!( + ERR_SOLD_OUT.ends_with(ERR_BUY_ABORTED_SUFFIX), + "the sold-out refusal shares the fail-closed abort suffix" + ); + } + // The dev buy loop (free ownership ledger, no on-chain payment) is a `dev-modes`-only path // now that rights_mode() defaults to Chain (DEV_MODE_GUARD_SPEC): without `dev-modes`, an // unset ELASTOS_DDRM_RIGHTS resolves to Chain, so this dev-ledger flow is unreachable. @@ -850,18 +990,24 @@ mod tests { #[cfg(feature = "dev-modes")] fn dev_buy_records_ownership_and_returns_hash() { let _g = crate::api::ddrm_env_lock(); - let dir = std::env::temp_dir().join(format!("buy-dev-{}", std::process::id())); - std::fs::create_dir_all(&dir).unwrap(); + let tmp = tempfile::tempdir().unwrap(); + let dir = tmp.path().to_path_buf(); std::env::set_var("ELASTOS_DDRM_OWNED_LEDGER", dir.join("owned.json")); std::env::remove_var("ELASTOS_DDRM_RIGHTS"); // dev - let out = buy_access("did:test:alice", "bafyDEV", SUBJECT, 1_700_000_000).expect("dev buy"); + let out = buy_access( + "did:test:alice", + "bafyDEV", + SUBJECT, + 1_700_000_000, + &BuyTarget::default(), + ) + .expect("dev buy"); assert!(out.owned_now); assert!(out.tx_hash.starts_with("0x")); assert!(super::super::owned_ledger::contains("bafyDEV", SUBJECT)); std::env::remove_var("ELASTOS_DDRM_OWNED_LEDGER"); - let _ = std::fs::remove_dir_all(&dir); } #[test] @@ -916,7 +1062,16 @@ mod tests { ); std::env::remove_var("ELASTOS_DDRM_RIGHTS"); let err = result.expect_err("chain buy with no wallet must error"); - assert!(err.contains("wallet not linked"), "unexpected error: {err}"); + // Sprint 43: wallet-not-linked is refused strictly before any broadcast, so buy_access + // CONSTRUCTS a PreBroadcast (refundable) error — the DRM rail refunds it by variant. + assert!( + matches!(err, BuyError::PreBroadcast(_)), + "wallet-not-linked is a pre-broadcast refusal: {err:?}" + ); + assert!( + err.message().contains("wallet not linked"), + "unexpected error: {err}" + ); } fn clear_buy_env() { @@ -986,8 +1141,13 @@ mod tests { &BuyTarget::default(), ) .expect_err("live buy without a resolved tokenId must fail closed"); + // A sourcing failure is strictly pre-broadcast ⇒ a refundable PreBroadcast. + assert!( + matches!(err, BuyError::PreBroadcast(_)), + "a live sourcing failure is pre-broadcast: {err:?}" + ); assert!( - err.contains("resolved on-chain tokenId"), + err.message().contains("resolved on-chain tokenId"), "unexpected error: {err}" ); std::env::remove_var("ELASTOS_DDRM_RIGHTS"); @@ -1119,8 +1279,8 @@ mod tests { #[ignore] fn chain_mock_buy_records_then_ledger_reads_owned() { let _g = crate::api::ddrm_env_lock(); - let dir = std::env::temp_dir().join(format!("buy-mock-{}", std::process::id())); - std::fs::create_dir_all(&dir).unwrap(); + let tmp = tempfile::tempdir().unwrap(); + let dir = tmp.path().to_path_buf(); std::env::set_var("ELASTOS_DDRM_OWNED_LEDGER", dir.join("owned.json")); std::env::set_var("ELASTOS_DDRM_RIGHTS", "chain-mock"); @@ -1140,7 +1300,6 @@ mod tests { std::env::remove_var("ELASTOS_DDRM_RIGHTS"); std::env::remove_var("ELASTOS_DDRM_OWNED_LEDGER"); - let _ = std::fs::remove_dir_all(&dir); } /// DEV INTEGRATION (opt-in): THE headline loop — in `chain-mock` + ledger-gated rights, @@ -1153,8 +1312,8 @@ mod tests { #[ignore] fn buy_then_open_loop_flips_rights_from_denied_to_allowed() { let _g = crate::api::ddrm_env_lock(); - let dir = std::env::temp_dir().join(format!("buy-loop-{}", std::process::id())); - std::fs::create_dir_all(&dir).unwrap(); + let tmp = tempfile::tempdir().unwrap(); + let dir = tmp.path().to_path_buf(); std::env::set_var("ELASTOS_DDRM_OWNED_LEDGER", dir.join("owned.json")); std::env::set_var("ELASTOS_DDRM_RIGHTS", "chain-mock"); // The mock answers ownership from the local ledger (the buy-flow gate). @@ -1197,7 +1356,6 @@ mod tests { std::env::remove_var("ELASTOS_DDRM_CHAIN_ACCESS"); std::env::remove_var("ELASTOS_DDRM_RIGHTS"); std::env::remove_var("ELASTOS_DDRM_OWNED_LEDGER"); - let _ = std::fs::remove_dir_all(&dir); } /// DEV INTEGRATION (opt-in): proves the REAL signing rail offline — the wallet capsule @@ -1212,8 +1370,8 @@ mod tests { #[ignore] fn chain_mock_wallet_signs_and_broadcasts_real_tx() { let _g = crate::api::ddrm_env_lock(); - let dir = std::env::temp_dir().join(format!("buy-wallet-{}", std::process::id())); - std::fs::create_dir_all(&dir).unwrap(); + let tmp = tempfile::tempdir().unwrap(); + let dir = tmp.path().to_path_buf(); std::env::set_var("ELASTOS_DDRM_OWNED_LEDGER", dir.join("owned.json")); std::env::set_var("ELASTOS_DDRM_WALLET_BASE", dir.join("wallet")); std::env::set_var("ELASTOS_DDRM_RIGHTS", "chain-mock"); @@ -1248,6 +1406,311 @@ mod tests { std::env::remove_var("ELASTOS_DDRM_RIGHTS"); std::env::remove_var("ELASTOS_DDRM_WALLET_BASE"); std::env::remove_var("ELASTOS_DDRM_OWNED_LEDGER"); - let _ = std::fs::remove_dir_all(&dir); + } + + /// Sprint 43 (the hostile-provider ratchet, END-TO-END): a chain-provider that FAILS the + /// broadcast op with a message embedding a pre-broadcast sentinel is typed `Indeterminate` by + /// CONSTRUCTION — the tx may have landed, so it keeps its reservation regardless of the + /// provider's bytes. This is the property the old string classifier had to defend with a + /// substring exclusion; now it is the type of the broadcast call site. + #[test] + #[cfg(all(unix, feature = "dev-modes"))] + fn a_broadcast_op_error_types_the_buy_as_indeterminate_even_with_a_sentinel() { + let _g = crate::api::ddrm_env_lock(); + let dir = tempfile::tempdir().unwrap(); + // A hostile chain-provider: answers init OK, then FAILS the broadcast op with a message + // that embeds a pre-broadcast sentinel to try to provoke a refund. + let stub = dir.path().join("hostile-chain.sh"); + std::fs::write( + &stub, + "#!/bin/sh\nread _init\nprintf '{\"status\":\"ok\"}\\n'\nread _op\n\ + printf '{\"status\":\"error\",\"message\":\"broadcast rejected: buy aborted (fail \ + closed)\"}\\n'\n", + ) + .unwrap(); + use std::os::unix::fs::PermissionsExt as _; + std::fs::set_permissions(&stub, std::fs::Permissions::from_mode(0o755)).unwrap(); + + std::env::set_var("ELASTOS_DDRM_RIGHTS", "chain-mock"); + std::env::set_var("ELASTOS_CHAIN_PROVIDER_BIN", &stub); + std::env::set_var("ELASTOS_DDRM_OWNED_LEDGER", dir.path().join("owned.json")); + // No wallet signing → the plain chain-mock broadcast path (broadcast_mock). + std::env::remove_var("ELASTOS_DDRM_BUY_SIGN"); + + let err = buy_access( + "did:test:alice", + "bafyX", + SUBJECT, + 1_700_000_000, + &BuyTarget::default(), + ) + .expect_err("a failing broadcast op must error"); + + std::env::remove_var("ELASTOS_DDRM_RIGHTS"); + std::env::remove_var("ELASTOS_CHAIN_PROVIDER_BIN"); + std::env::remove_var("ELASTOS_DDRM_OWNED_LEDGER"); + + assert!( + matches!(err, BuyError::Indeterminate(_)), + "a broadcast-op failure is post-broadcast ⇒ Indeterminate/hold, NOT a refund: {err:?}" + ); + assert!( + err.message().contains(ERR_BUY_ABORTED_SUFFIX), + "the sentinel IS present in the message but did NOT flip the classification: {err}" + ); + } + + /// Sprint 43 (replaces the wallet-sign marker classification test): the wallet SIGN leg runs + /// strictly before broadcast, so a hung signer is typed `PreBroadcast` by CONSTRUCTION — the tx + /// was never signed, so the DRM rail refunds. Proven end-to-end through `buy_access`. + #[test] + #[cfg(all(unix, feature = "dev-modes"))] + fn a_wallet_sign_timeout_types_the_buy_as_pre_broadcast() { + let _g = crate::api::ddrm_env_lock(); + let dir = tempfile::tempdir().unwrap(); + let stub = dir.path().join("hung-wallet.sh"); + std::fs::write(&stub, "#!/bin/sh\nsleep 300\n").unwrap(); + use std::os::unix::fs::PermissionsExt as _; + std::fs::set_permissions(&stub, std::fs::Permissions::from_mode(0o755)).unwrap(); + + let prior_deadline = std::env::var("ELASTOS_CHAIN_READ_DEADLINE_SECS").ok(); + std::env::set_var("ELASTOS_DDRM_RIGHTS", "chain-mock"); + std::env::set_var("ELASTOS_DDRM_BUY_SIGN", "wallet"); + std::env::set_var("ELASTOS_WALLET_PROVIDER_BIN", &stub); + std::env::set_var("ELASTOS_DDRM_WALLET_BASE", dir.path().join("wallet")); + std::env::set_var("ELASTOS_CHAIN_READ_DEADLINE_SECS", "1"); + + let started = std::time::Instant::now(); + let err = buy_access( + "did:test:alice", + "bafyX", + "", + 1_700_000_000, + &BuyTarget::default(), + ) + .expect_err("a hung wallet signer must error"); + + std::env::remove_var("ELASTOS_DDRM_RIGHTS"); + std::env::remove_var("ELASTOS_DDRM_BUY_SIGN"); + std::env::remove_var("ELASTOS_WALLET_PROVIDER_BIN"); + std::env::remove_var("ELASTOS_DDRM_WALLET_BASE"); + match prior_deadline { + Some(v) => std::env::set_var("ELASTOS_CHAIN_READ_DEADLINE_SECS", v), + None => std::env::remove_var("ELASTOS_CHAIN_READ_DEADLINE_SECS"), + } + + assert!( + started.elapsed() < std::time::Duration::from_secs(15), + "the sign leg is bounded by the deadline, not the stub's 300s sleep" + ); + assert!( + matches!(err, BuyError::PreBroadcast(_)), + "a sign-leg timeout is pre-broadcast ⇒ refund: {err:?}" + ); + assert!( + err.message() + .contains(crate::api::wallet_signer::WALLET_SIGN_DEADLINE_MARKER), + "the pre-broadcast error carries the sign-deadline marker: {err}" + ); + } + + /// Sprint 46 (the dedicated PREPARE-leg ratchet — council S43 guardian F2): a chain-provider + /// that answers the LISTING read but HANGS on `prepare_transaction` (the nonce/gas READ inside + /// the sign closure) is killed at the deadline and the buy is typed `PreBroadcast` ⇒ refund — + /// the tx was never signed, so it provably never broadcast. This is the S43 refinement's own + /// test: the same `CHAIN_DEADLINE_MARKER` on the SEND leg stays Indeterminate (proven by + /// `a_broadcast_op_error_types_the_buy_as_indeterminate_even_with_a_sentinel`); here the marker + /// rides a refund because the CALL SITE — not the message — decides. Guards the ordering + /// invariant a refactor could silently break (hoisting the prepare out of the sign closure, or + /// reusing one provider session for prepare+broadcast). + #[test] + #[cfg(all(unix, feature = "dev-modes"))] + fn a_chain_prepare_deadline_types_the_buy_as_pre_broadcast() { + let _g = crate::api::ddrm_env_lock(); + let dir = tempfile::tempdir().unwrap(); + use std::os::unix::fs::PermissionsExt as _; + + // Chain-provider: fresh subprocess per conversation. Answers any read op with a VALID + // listing return (qty=5, price=1_000_000, native pay token) — but HANGS on the + // prepare_transaction op. + let listing_result = format!("0x{:064x}{:064x}{}", 5u128, 1_000_000u128, "0".repeat(64)); + let chain_stub = dir.path().join("prepare-hang-chain.sh"); + std::fs::write( + &chain_stub, + format!( + "#!/bin/sh\nread _init\nprintf '{{\"status\":\"ok\",\"data\":{{}}}}\\n'\n\ + read op\ncase \"$op\" in\n *prepare_transaction*) sleep 300;;\n *) printf \ + '{{\"status\":\"ok\",\"data\":{{\"result\":\"{listing_result}\"}}}}\\n';;\nesac\n" + ), + ) + .unwrap(); + std::fs::set_permissions(&chain_stub, std::fs::Permissions::from_mode(0o755)).unwrap(); + + // Wallet-provider: a persistent session that answers init + create_managed_account, then + // waits — the buy dies on the chain PREPARE inside the sign closure before any further leg. + let wallet_stub = dir.path().join("ready-wallet.sh"); + std::fs::write( + &wallet_stub, + "#!/bin/sh\nread _init\nprintf '{\"status\":\"ok\",\"data\":{}}\\n'\nread _create\n\ + printf '{\"status\":\"ok\",\"data\":{\"account\":{\"account_id\":\"acc1\",\ + \"address\":\"0x00000000000000000000000000000000000000aa\"}}}\\n'\nread _never\n\ + sleep 300\n", + ) + .unwrap(); + std::fs::set_permissions(&wallet_stub, std::fs::Permissions::from_mode(0o755)).unwrap(); + + let prior_deadline = std::env::var("ELASTOS_CHAIN_READ_DEADLINE_SECS").ok(); + std::env::set_var("ELASTOS_DDRM_RIGHTS", "chain"); + std::env::set_var("ELASTOS_DDRM_BUY_SIGN", "wallet"); + std::env::set_var("ELASTOS_CHAIN_PROVIDER_BIN", &chain_stub); + std::env::set_var("ELASTOS_WALLET_PROVIDER_BIN", &wallet_stub); + std::env::set_var("ELASTOS_DDRM_WALLET_BASE", dir.path().join("wallet")); + std::env::set_var("ELASTOS_CHAIN_BASE_RPC", "http://127.0.0.1:9"); + std::env::set_var("ELASTOS_DDRM_CHAIN_ID", "84532"); + // Pin the buy terms so the only pre-sign chain conversation is the listing re-read. + std::env::set_var( + "ELASTOS_DDRM_BUY_LEDGER", + "0x1111111111111111111111111111111111111111", + ); + std::env::set_var("ELASTOS_DDRM_BUY_TOKEN_ID", "7"); + std::env::set_var( + "ELASTOS_DDRM_BUY_OPERATIVE", + "0x8b0ae79abf9b41dfe8aabf3c791dd52fe7713530", + ); + std::env::set_var( + "ELASTOS_DDRM_BUY_SELLER", + "0x34daf31b99b5a59ceb18e424dbc112fa6e5f3dc3", + ); + std::env::set_var("ELASTOS_CHAIN_READ_DEADLINE_SECS", "1"); + + let started = std::time::Instant::now(); + let err = buy_access( + "did:test:alice", + "bafyPREPARE", + "", + 1_700_000_000, + &BuyTarget::default(), + ) + .expect_err("a hung prepare leg must error"); + + for k in [ + "ELASTOS_DDRM_RIGHTS", + "ELASTOS_DDRM_BUY_SIGN", + "ELASTOS_CHAIN_PROVIDER_BIN", + "ELASTOS_WALLET_PROVIDER_BIN", + "ELASTOS_DDRM_WALLET_BASE", + "ELASTOS_CHAIN_BASE_RPC", + "ELASTOS_DDRM_CHAIN_ID", + "ELASTOS_DDRM_BUY_LEDGER", + "ELASTOS_DDRM_BUY_TOKEN_ID", + "ELASTOS_DDRM_BUY_OPERATIVE", + "ELASTOS_DDRM_BUY_SELLER", + ] { + std::env::remove_var(k); + } + match prior_deadline { + Some(v) => std::env::set_var("ELASTOS_CHAIN_READ_DEADLINE_SECS", v), + None => std::env::remove_var("ELASTOS_CHAIN_READ_DEADLINE_SECS"), + } + + assert!( + started.elapsed() < std::time::Duration::from_secs(15), + "the prepare leg is bounded by the deadline, not the stub's 300s sleep" + ); + assert!( + matches!(err, BuyError::PreBroadcast(_)), + "a chain deadline on the PREPARE (read) leg is pre-broadcast ⇒ refund: {err:?}" + ); + assert!( + err.message() + .contains(crate::api::rights_authority::CHAIN_DEADLINE_MARKER), + "the refund-classified error carries the CHAIN deadline marker — the same marker the \ + SEND leg holds as Indeterminate; the call site decides, not the bytes: {err}" + ); + } + + /// Sprint 43 council F3a: a Dev-mode buy NEVER broadcasts (synthetic hash, local ledger), so a + /// record failure is pre-broadcast ⇒ refundable. This is a behavior CHANGE the typing makes + /// correct — the old string classifier had no sentinel for it and stranded it as Indeterminate. + #[test] + #[cfg(feature = "dev-modes")] + fn a_dev_record_failure_types_the_buy_as_pre_broadcast() { + let _g = crate::api::ddrm_env_lock(); + let dir = tempfile::tempdir().unwrap(); + // Make the ledger's parent a FILE so `owned_ledger::record`'s write fails (ENOTDIR). + std::fs::write(dir.path().join("blocker"), b"x").unwrap(); + let prior = std::env::var("ELASTOS_DDRM_RIGHTS").ok(); + std::env::remove_var("ELASTOS_DDRM_RIGHTS"); // dev + std::env::set_var( + "ELASTOS_DDRM_OWNED_LEDGER", + dir.path().join("blocker").join("owned.json"), + ); + + let err = buy_access( + "did:test:a", + "bafyDEV", + SUBJECT, + 1_700_000_000, + &BuyTarget::default(), + ) + .expect_err("an unwritable dev ledger must error"); + + std::env::remove_var("ELASTOS_DDRM_OWNED_LEDGER"); + match prior { + Some(v) => std::env::set_var("ELASTOS_DDRM_RIGHTS", v), + None => std::env::remove_var("ELASTOS_DDRM_RIGHTS"), + } + assert!( + matches!(err, BuyError::PreBroadcast(_)), + "dev never broadcasts ⇒ a record failure is a pre-broadcast refund: {err:?}" + ); + } + + /// Sprint 43 council F3b: a record failure AFTER a SUCCESSFUL broadcast is `Indeterminate` — the + /// tx is out, so the reservation is kept, never refunded. Proves the post-broadcast `record` + /// call site's typing end-to-end (chain-mock broadcast succeeds; the ledger write then fails). + #[test] + #[cfg(all(unix, feature = "dev-modes"))] + fn a_post_broadcast_record_failure_types_the_buy_as_indeterminate() { + let _g = crate::api::ddrm_env_lock(); + let dir = tempfile::tempdir().unwrap(); + // A chain-provider that SUCCEEDS the broadcast op with a valid tx hash. + let stub = dir.path().join("ok-broadcast.sh"); + std::fs::write( + &stub, + "#!/bin/sh\nread _i\nprintf '{\"status\":\"ok\"}\\n'\nread _o\nprintf \ + '{\"status\":\"ok\",\"data\":{\"transaction_hash\":\"0x00000000000000000000000000000\ + 00000000000000000000000000000000001\"}}\\n'\n", + ) + .unwrap(); + use std::os::unix::fs::PermissionsExt as _; + std::fs::set_permissions(&stub, std::fs::Permissions::from_mode(0o755)).unwrap(); + // ...but the ledger write (which runs AFTER the broadcast) fails. + std::fs::write(dir.path().join("blocker"), b"x").unwrap(); + + std::env::set_var("ELASTOS_DDRM_RIGHTS", "chain-mock"); + std::env::set_var("ELASTOS_CHAIN_PROVIDER_BIN", &stub); + std::env::set_var( + "ELASTOS_DDRM_OWNED_LEDGER", + dir.path().join("blocker").join("owned.json"), + ); + std::env::remove_var("ELASTOS_DDRM_BUY_SIGN"); + + let err = buy_access( + "did:test:a", + "bafyX", + SUBJECT, + 1_700_000_000, + &BuyTarget::default(), + ) + .expect_err("a post-broadcast record failure must error"); + + std::env::remove_var("ELASTOS_DDRM_RIGHTS"); + std::env::remove_var("ELASTOS_CHAIN_PROVIDER_BIN"); + std::env::remove_var("ELASTOS_DDRM_OWNED_LEDGER"); + assert!( + matches!(err, BuyError::Indeterminate(_)), + "a record failure after a successful broadcast is Indeterminate (tx may be out): {err:?}" + ); } } diff --git a/elastos/crates/elastos-server/src/api/capsule_watchdog.rs b/elastos/crates/elastos-server/src/api/capsule_watchdog.rs new file mode 100644 index 00000000..b6faf0a9 --- /dev/null +++ b/elastos/crates/elastos-server/src/api/capsule_watchdog.rs @@ -0,0 +1,544 @@ +//! The ONE subprocess-conversation watchdog (Sprint 40/41): bounds ANY capsule-provider +//! conversation so no runtime thread ever parks forever on a hung or hostile subprocess. +//! +//! Sprint 40 bounded the chain-provider conversation; Sprint 41 factored that discipline here so +//! the chain, rights, and wallet providers share ONE implementation of the subtle bits — the +//! process-group spawn, the disarm-before-reap ordering (a recycled pid can never take a stray +//! group kill), the length-capped read, and the shared deadline knob. No third copy of the +//! ordering to drift. +//! +//! UNIX-ONLY kill (like the flock protections): elsewhere the watchdog is a stated no-op and the +//! old unbounded behavior remains. + +use std::io::{BufRead, Read}; +use std::process::{Child, Command, ExitStatus}; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::mpsc; +use std::sync::Arc; +use std::thread::JoinHandle; +use std::time::Duration; + +use serde_json::Value; + +/// Longest single response line a capsule may emit. A JSON-RPC response is kilobytes; this is a +/// generous ceiling that turns a hostile/compromised provider streaming a newline-free firehose +/// (memory-exhaustion DoS within the deadline window — council S40 red-team F2) into a bounded +/// error instead of an OOM abort of the whole runtime. +pub(crate) const MAX_CAPSULE_LINE: u64 = 4 * 1024 * 1024; + +/// How long ONE provider conversation (spawn → init → op → response) may take before the child is +/// killed. `ELASTOS_CHAIN_READ_DEADLINE_SECS` (kept as the shared name — one deadline for every +/// provider), default 30. A malformed value (or `< 1`) uses the DEFAULT with a loud warning: the +/// deadline is an availability protection, not a money decision, so a typo must not silently +/// remove it (fail SAFE, not fail open-ended). Set it ABOVE your P99 RPC roundtrip — too low +/// forces every live op to time out, the safe money direction but a real availability cliff. +pub(crate) fn capsule_read_deadline() -> Duration { + const DEFAULT_SECS: u64 = 30; + let secs = match std::env::var("ELASTOS_CHAIN_READ_DEADLINE_SECS") { + Ok(raw) => match raw.trim().parse::() { + Ok(n) if n >= 1 => n, + _ => { + tracing::warn!( + "ELASTOS_CHAIN_READ_DEADLINE_SECS={raw:?} is not a positive integer — \ + using the default {DEFAULT_SECS}s deadline" + ); + DEFAULT_SECS + } + }, + Err(_) => DEFAULT_SECS, + }; + Duration::from_secs(secs) +} + +/// The ONE list of runtime-only secrets stripped from every capsule spawn (Sprint 46 — P16/P5). +/// Defined in `elastos_runtime::provider` so EVERY capsule spawn seam (this watchdog's +/// `spawn_grouped`, `ProviderBridge::spawn`, the carrier service spawn, and the shell-capsule +/// spawns in main/serve_cmd) shares it — see its docs for the threat model. The council S46 +/// red-team proved a local copy here was not enough: the general provider seams bypassed it and +/// leaked the rail bearer to every provider capsule. The source-structural guard test below pins +/// every spawn site in the tree onto a classified seam. +use elastos_runtime::provider::RUNTIME_ONLY_SECRETS; + +/// Spawn a command in its OWN process group (unix) so a deadline kill takes down the provider AND +/// anything it spawned — a killed parent whose helper child still holds the stdout pipe would +/// leave the read blocked past the deadline (exactly the hang the deadline exists to end). +/// Also strips [`RUNTIME_ONLY_SECRETS`] from the child's environment (P16) — see the const's docs. +pub(crate) fn spawn_grouped(cmd: &mut Command) -> std::io::Result { + for secret in RUNTIME_ONLY_SECRETS { + cmd.env_remove(secret); + } + #[cfg(unix)] + { + use std::os::unix::process::CommandExt as _; + cmd.process_group(0); + } + cmd.spawn() +} + +/// A watchdog that group-SIGKILLs `pid` after `deadline` unless disarmed first. +/// +/// ORDERING CONTRACT (council S40 red-team F1 / guardian F3): call [`disarm`](Self::disarm) +/// (which disarms AND joins) BEFORE reaping the child. The watchdog can then only ever kill a +/// child that has NOT yet been reaped, so a reaped-then-recycled pid can never receive a stray +/// group kill. For a persistent session (wallet), the child is reaped only at session drop, so +/// arm/disarm per read is safe by the same argument. +pub(crate) struct DeadlineWatchdog { + fired: Arc, + disarm_tx: mpsc::Sender<()>, + handle: Option>, +} + +impl DeadlineWatchdog { + /// Arm a watchdog for `pid` (the child's own process group). Off-unix this is a no-op that + /// never fires (the read stays unbounded, as stated). + pub(crate) fn arm(pid: u32, deadline: Duration) -> Self { + let fired = Arc::new(AtomicBool::new(false)); + let (disarm_tx, disarm_rx) = mpsc::channel::<()>(); + let handle = { + let fired = fired.clone(); + std::thread::spawn(move || { + if disarm_rx.recv_timeout(deadline).is_err() { + // `fired` is set ONLY where a kill actually happens (unix), so a deadline + // error is never minted on a platform where nothing was killed (S40 G-F2). + #[cfg(unix)] + { + // A pid of 0 would make `kill(-0)` signal the CALLER's OWN process group — + // runtime suicide dressed as an availability protection (council S42 + // guardian F2). No legitimate child has pid 0; refuse to kill on it (and do + // not set `fired`, so no bogus deadline error is minted either). + if pid != 0 { + fired.store(true, Ordering::SeqCst); + unsafe { + libc::kill(-(pid as i32), libc::SIGKILL); + } + } else { + tracing::error!( + "DeadlineWatchdog armed on pid 0 — refusing kill(-0) (it would \ + signal the runtime's own process group)" + ); + } + } + #[cfg(not(unix))] + { + let _ = (&fired, pid); + } + } + }) + }; + Self { + fired, + disarm_tx, + handle: Some(handle), + } + } + + /// Disarm AND join the watchdog thread, returning whether it fired (killed the group). MUST + /// be called before reaping the child (see the ordering contract). + pub(crate) fn disarm(mut self) -> bool { + let _ = self.disarm_tx.send(()); + if let Some(h) = self.handle.take() { + let _ = h.join(); + } + self.fired.load(Ordering::SeqCst) + } +} + +impl Drop for DeadlineWatchdog { + fn drop(&mut self) { + // Defensive (council S41 guardian F2): a watchdog dropped WITHOUT an explicit `disarm` + // (e.g. a future `?` early-return slipped between arm and disarm) would otherwise leave + // the timer thread running until the FULL deadline and THEN group-kill — a latent stray + // kill in a shared module. Disarming on drop makes an un-disarmed watchdog a no-op, not a + // loaded gun. `disarm` takes `self` by value so it also drops through here, but it has + // already sent and taken the handle: this send no-ops on the closed channel and the join + // is skipped. + let _ = self.disarm_tx.send(()); + if let Some(h) = self.handle.take() { + let _ = h.join(); + } + } +} + +/// Reap a grouped capsule child WITHOUT reintroducing an unbounded park. The disarm-before-reap +/// ordering ends the *read* deadline, but a provider that answered every op and then refuses to +/// exit on EOF/`shutdown` would wedge the runtime thread on a plain `child.wait()` forever — the +/// very hang the deadline exists to end, slipped past the read into the reap (council S41 guardian +/// F1/F2). Call this AFTER [`DeadlineWatchdog::disarm`]: it gives the child a brief grace to exit +/// cleanly (the normal path), then group-SIGKILLs and reaps. `try_wait` never blocks and does not +/// free the pid until the child has actually exited, so the group-kill always targets our OWN +/// un-reaped child — the pid-reuse invariant that governs the whole module still holds. +/// +/// Off-unix there is no group kill (as stated module-wide): the grace lapses and the final `wait` +/// is the old unbounded behavior. +/// +/// Returns the child's [`ExitStatus`] when it could be collected (so a one-shot caller can fold a +/// non-success exit into its error), or `None` if `try_wait` itself errored. +pub(crate) fn reap_grouped(child: &mut Child) -> Option { + const GRACE_TICKS: u32 = 20; + const TICK: Duration = Duration::from_millis(50); // ~1s total grace for a clean exit + for _ in 0..GRACE_TICKS { + match child.try_wait() { + Ok(Some(status)) => return Some(status), // exited on its own — reaped, nothing to kill + Ok(None) => std::thread::sleep(TICK), + Err(_) => return None, // cannot reap here; the guard/session Drop reap is the backstop + } + } + #[cfg(unix)] + { + // Still alive after the grace: end the conversation for good. The child is un-reaped, so + // its group id is still ours — the kill cannot land on a recycled pid. + unsafe { + libc::kill(-(child.id() as i32), libc::SIGKILL); + } + } + child.wait().ok() +} + +/// A spawned capsule child that is BOUNDED-reaped on drop unless explicitly disarmed. Between spawn +/// and the moment the child is handed to its long-lived owner, MANY fallible steps run (take +/// stdin/stdout, read + parse a descriptor, extract fields) — every early return among them must +/// reap the child, or a hostile sidecar that forces one (a well-formed-but-incomplete descriptor, +/// an EPIPE on the first write, a self-exit) leaks a live process or a zombie (council S42 red-team +/// F1/F2). `std::process::Child::drop` neither kills nor waits, so this guard closes that gap: on +/// success `disarm()` transfers the child to the owner; on ANY early return the `Drop` reaps it via +/// [`reap_grouped`] (group-kill after a grace). This is the ONE reap-guard the access sidecars +/// share (P5) so the discipline cannot drift across copies. +pub(crate) struct ReapGuard(Option); + +impl ReapGuard { + pub(crate) fn new(child: Child) -> Self { + Self(Some(child)) + } + /// The armed child (present until [`disarm`](Self::disarm)); for taking stdin/stdout. + pub(crate) fn child_mut(&mut self) -> &mut Child { + self.0.as_mut().expect("child present until disarm") + } + /// The armed child's pid (its own process group), for arming a read watchdog on it. Panics + /// rather than ever returning 0 — a `kill(-0)` would signal the GATEWAY's own group (council + /// S42 red-team F4). The child is present until disarm by construction. + pub(crate) fn pid(&self) -> u32 { + self.0 + .as_ref() + .map(Child::id) + .expect("child present until disarm") + } + /// Success path: transfer the child out to its long-lived owner, disarming the guard. + pub(crate) fn disarm(mut self) -> Child { + self.0.take().expect("child present until disarm") + } +} + +impl Drop for ReapGuard { + fn drop(&mut self) { + if let Some(mut child) = self.0.take() { + reap_grouped(&mut child); + } + } +} + +/// How long a CONTENT-OPEN conversation (spawn → transcode/seal handshake → first descriptor line) +/// may take before the sidecar is killed. SEPARATE from [`capsule_read_deadline`] because a media +/// open runs ffmpeg + a seal handshake BEFORE it answers, so the RPC-tuned 30s would group-kill a +/// legitimate slow transcode and DENY the honest open (council S42 red-team F3 — an availability +/// cliff). `ELASTOS_CONTENT_OPEN_DEADLINE_SECS`, default 120; malformed/`< 1` ⇒ default with a +/// loud warning (the deadline is an availability protection, not a money decision — a typo must not +/// silently remove it). The per-op VIEW reads (segment/page/object) and the grant crypto keep the +/// shorter [`capsule_read_deadline`] — they are quick relays, not a transcode. +pub(crate) fn content_open_deadline() -> Duration { + const DEFAULT_SECS: u64 = 120; + let secs = match std::env::var("ELASTOS_CONTENT_OPEN_DEADLINE_SECS") { + Ok(raw) => match raw.trim().parse::() { + Ok(n) if n >= 1 => n, + _ => { + tracing::warn!( + "ELASTOS_CONTENT_OPEN_DEADLINE_SECS={raw:?} is not a positive integer — \ + using the default {DEFAULT_SECS}s content-open deadline" + ); + DEFAULT_SECS + } + }, + Err(_) => DEFAULT_SECS, + }; + Duration::from_secs(secs) +} + +/// Read one newline-delimited JSON response line from a capsule's stdout, LENGTH-bounded to +/// [`MAX_CAPSULE_LINE`] so a firehose provider is a bounded error, not an OOM. +pub(crate) fn read_capsule_line(reader: impl BufRead) -> Result { + let mut line = String::new(); + // `take` caps the bytes read this call; a line at/over the cap is refused rather than grown + // unbounded. `read_line` still stops at the first newline within the cap. Taking the reader + // by value (callers pass `&mut reader`, and `&mut R: BufRead`) sidesteps the double-reference + // method-resolution snag `.take()` hits on a `&mut impl BufRead`. + let n = reader + .take(MAX_CAPSULE_LINE + 1) + .read_line(&mut line) + .map_err(|e| format!("read capsule stdout: {e}"))?; + if n == 0 { + return Err("capsule exited before answering".to_string()); + } + if line.len() as u64 > MAX_CAPSULE_LINE { + return Err("capsule response line exceeds the size cap (refused)".to_string()); + } + serde_json::from_str(line.trim()).map_err(|e| format!("parse capsule response: {e}")) +} + +/// The marker an ACCESS-path (content open/view) deadline carries (Sprint 42). ACCESS NOTE: a +/// content-authority timeout is a DENY (fail-closed) — the exact mirror of the rights-decide rule +/// (`RIGHTS_DEADLINE_MARKER`), never a money decision. The sidecars this bounds (the media/object +/// authorities and the grant sidecar) sit on the OPEN and VIEW paths, not the pay spine, so a +/// timeout simply refuses the open/read; there is no charge to classify. +pub(crate) const ACCESS_DEADLINE_MARKER: &str = "content-authority read deadline exceeded"; + +/// Read one capsule response line bounded by an explicit `deadline`: arm a watchdog on `child_pid`'s +/// process group, read (length-capped), disarm. On a fire the child's group is SIGKILLed and this +/// returns an [`ACCESS_DEADLINE_MARKER`] error so the caller DENIES (fail-closed) — no access thread +/// parks forever on a hung content-authority sidecar. `what` names the sidecar for diagnostics. +/// +/// This arms/disarms per read but does NOT reap — a persistent session reaps its child once at Drop +/// (via [`reap_grouped`]), so the disarm-before-reap ordering holds by construction (every per-read +/// disarm precedes the single Drop reap). After a fire the child is dead; the session's next read +/// EOFs and denies again (fail-closed), and Drop reaps the corpse. +/// +/// NOTE: only the READ is watchdog-bounded. The paired request WRITE (the caller's `writeln!` of a +/// one-line JSON op) runs before this and is NOT bounded — it is safe because every op payload is a +/// short JSON line far below the OS pipe buffer, so the kernel accepts it without blocking on the +/// child draining. A future op with a payload approaching the pipe buffer would need its own bound. +fn read_line_deadlined_with( + child_pid: u32, + reader: impl BufRead, + what: &str, + deadline: Duration, +) -> Result { + let watchdog = DeadlineWatchdog::arm(child_pid, deadline); + let read = read_capsule_line(reader); + let fired = watchdog.disarm(); + if fired { + // Fail closed whether or not a late response also landed: a response the watchdog had to + // kill for is by definition past the deadline, so denying it is the correct direction. + return Err(format!( + "{ACCESS_DEADLINE_MARKER}: no response within {}s — {what} killed; access DENIED \ + (fail-closed)", + deadline.as_secs() + )); + } + read +} + +/// Bound a per-op VIEW read (segment/page/object relay) with the shorter [`capsule_read_deadline`] +/// — these are quick relays, not a transcode. +pub(crate) fn read_line_deadlined( + child_pid: u32, + reader: impl BufRead, + what: &str, +) -> Result { + read_line_deadlined_with(child_pid, reader, what, capsule_read_deadline()) +} + +/// Bound a content-OPEN descriptor read with the longer [`content_open_deadline`] — the sidecar +/// runs ffmpeg + a seal handshake before it answers, so the RPC-tuned deadline would kill an honest +/// slow open (council S42 red-team F3). +pub(crate) fn read_open_deadlined( + child_pid: u32, + reader: impl BufRead, + what: &str, +) -> Result { + read_line_deadlined_with(child_pid, reader, what, content_open_deadline()) +} + +/// Run a ONE-SHOT capsule read-to-EOF bounded by the shared [`capsule_read_deadline`]: arm a +/// watchdog on `child`'s group, read ALL of `stdout` to EOF (length-capped to [`MAX_CAPSULE_LINE`], +/// so a firehose sidecar is a bounded error not an OOM), disarm, then reap. Unlike the persistent +/// per-line readers this OWNS the reap (the child is single-use), so the caller must NOT also reap +/// — it hands the child in and this returns the parsed stdout (or a fail-closed error). On a fire +/// the group is SIGKILLed and this returns an [`ACCESS_DEADLINE_MARKER`] error; a non-success exit +/// status is folded into the error too (`what` names the sidecar). This is the ONE implementation +/// of the one-shot ordering — a caller (the grant sidecar) must not hand-roll it (council S42 +/// guardian F3). +pub(crate) fn read_to_eof_deadlined( + child: &mut Child, + mut stdout: impl Read, + what: &str, +) -> Result { + let deadline = capsule_read_deadline(); + let watchdog = DeadlineWatchdog::arm(child.id(), deadline); + let mut buf = String::new(); + let read = (&mut stdout) + .take(MAX_CAPSULE_LINE + 1) + .read_to_string(&mut buf); + let fired = watchdog.disarm(); + let status = reap_grouped(child); // disarm-before-reap: watchdog already joined above + if fired { + return Err(format!( + "{ACCESS_DEADLINE_MARKER}: no response within {}s — {what} killed; access DENIED \ + (fail-closed)", + deadline.as_secs() + )); + } + read.map_err(|e| format!("read {what} stdout: {e}"))?; + if buf.len() as u64 > MAX_CAPSULE_LINE { + return Err(format!("{what} output exceeds the size cap (refused)")); + } + if let Some(status) = status { + if !status.success() { + return Err(format!("{what} exited with {status} (open fails closed)")); + } + } + Ok(buf) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_malformed_deadline_env_keeps_the_default_protection() { + let _g = crate::api::ddrm_env_lock(); + let prior = std::env::var("ELASTOS_CHAIN_READ_DEADLINE_SECS").ok(); + std::env::set_var("ELASTOS_CHAIN_READ_DEADLINE_SECS", "soon"); + assert_eq!(capsule_read_deadline(), Duration::from_secs(30)); + std::env::set_var("ELASTOS_CHAIN_READ_DEADLINE_SECS", "0"); + assert_eq!(capsule_read_deadline(), Duration::from_secs(30)); + std::env::set_var("ELASTOS_CHAIN_READ_DEADLINE_SECS", "5"); + assert_eq!(capsule_read_deadline(), Duration::from_secs(5)); + match prior { + Some(v) => std::env::set_var("ELASTOS_CHAIN_READ_DEADLINE_SECS", v), + None => std::env::remove_var("ELASTOS_CHAIN_READ_DEADLINE_SECS"), + } + } + + /// Sprint 46 (P16, council S43 guardian F4): the runtime-only secrets NEVER reach a spawned + /// capsule's environment — a canary broadcastable-signed-tx set in the runtime env is ABSENT in + /// the child, while an ordinary `ELASTOS_*` config var still passes through. The strip lives at + /// `spawn_grouped` (the single spawn seam), so every provider/sidecar gets it for free. + #[test] + #[cfg(unix)] + fn runtime_only_secrets_are_stripped_from_spawned_capsules() { + let _g = crate::api::ddrm_env_lock(); + std::env::set_var("ELASTOS_DDRM_BUY_SIGNED_TX", "0xCANARY_SIGNED_TX"); + std::env::set_var("ELASTOS_PAYMENT_TOKEN", "canary-bearer"); + std::env::set_var("ELASTOS_S46_ORDINARY_CONFIG", "passes-through"); + + let mut cmd = Command::new("/bin/sh"); + cmd.arg("-c").arg( + "printf '%s|%s|%s' \ + \"${ELASTOS_DDRM_BUY_SIGNED_TX:-ABSENT}\" \ + \"${ELASTOS_PAYMENT_TOKEN:-ABSENT}\" \ + \"${ELASTOS_S46_ORDINARY_CONFIG:-ABSENT}\"", + ); + cmd.stdout(std::process::Stdio::piped()); + let child = spawn_grouped(&mut cmd).expect("spawn canary shell"); + let out = child.wait_with_output().expect("collect canary output"); + + std::env::remove_var("ELASTOS_DDRM_BUY_SIGNED_TX"); + std::env::remove_var("ELASTOS_PAYMENT_TOKEN"); + std::env::remove_var("ELASTOS_S46_ORDINARY_CONFIG"); + + let seen = String::from_utf8_lossy(&out.stdout).to_string(); + assert_eq!( + seen, "ABSENT|ABSENT|passes-through", + "secrets stripped, ordinary config inherited: {seen}" + ); + } + + /// Sprint 46 (council red-team F5 — the structural guard): every `Command::new` site in + /// elastos-server + elastos-runtime must be a KNOWN spawn seam. The three CAPSULE seams must + /// each reference `RUNTIME_ONLY_SECRETS` (the strip cannot be refactored away silently), and a + /// NEW file that starts spawning processes fails this test until it is consciously classified + /// here (capsule seam ⇒ add the strip; host tool ⇒ allowlist). This is what turns the canary + /// (which proves the helper strips) into a tree-wide invariant (every capsule spawn strips). + #[test] + fn every_command_spawn_site_is_a_known_seam_and_capsule_seams_strip_secrets() { + // The files that SPAWN CAPSULES — each must carry the strip (reference the shared list). + // capsule_watchdog (chain/wallet/rights/content sidecars), ProviderBridge (the general + // provider capsules), the carrier service, and the shell-capsule spawns in main/serve_cmd. + const CAPSULE_SEAMS: &[&str] = &[ + "crates/elastos-server/src/api/capsule_watchdog.rs", + "crates/elastos-server/src/carrier_service.rs", + "crates/elastos-runtime/src/provider/bridge.rs", + "crates/elastos-server/src/main.rs", + "crates/elastos-server/src/serve_cmd.rs", + ]; + // HOST-TOOL / self-exec spawn sites (git, tar, systemctl, the gateway re-exec, CLI + // conveniences) — not capsule spawns; they run operator-trusted binaries, not + // operator-PINNED provider capsules. Classify deliberately before adding here. + const HOST_TOOL_FILES: &[&str] = &[ + "crates/elastos-server/src/agent_cmd.rs", + "crates/elastos-server/src/api/access_grant.rs", + "crates/elastos-server/src/api/gateway_server.rs", + "crates/elastos-server/src/api/media_authority.rs", + "crates/elastos-server/src/api/object_authority.rs", + "crates/elastos-server/src/api/rights_authority.rs", + "crates/elastos-server/src/api/wallet_signer.rs", + "crates/elastos-server/src/chat_cmd.rs", + "crates/elastos-server/src/home_cmd.rs", + "crates/elastos-server/src/publish.rs", + "crates/elastos-server/src/runtime_control.rs", + "crates/elastos-server/src/server_infra.rs", + "crates/elastos-server/src/setup.rs", + "crates/elastos-server/src/update.rs", + ]; + // NOTE: access_grant/media/object/rights/wallet_signer BUILD their Command but spawn via + // `spawn_grouped` (this module) — they are allowlisted as "known" above because their + // spawn goes through the stripping seam; the guard below still requires the seam files + // themselves to reference the strip. + + let ws_root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")) + .parent() + .and_then(std::path::Path::parent) + .expect("workspace root") + .to_path_buf(); + + fn rs_files(dir: &std::path::Path, out: &mut Vec) { + let Ok(entries) = std::fs::read_dir(dir) else { + return; + }; + for e in entries.flatten() { + let p = e.path(); + if p.is_dir() { + rs_files(&p, out); + } else if p.extension().is_some_and(|x| x == "rs") { + out.push(p); + } + } + } + + let mut files = Vec::new(); + rs_files(&ws_root.join("crates/elastos-server/src"), &mut files); + rs_files(&ws_root.join("crates/elastos-runtime/src"), &mut files); + + let mut unknown = Vec::new(); + for f in &files { + let Ok(src) = std::fs::read_to_string(f) else { + continue; + }; + if !src.contains("Command::new(") { + continue; + } + let rel = f + .strip_prefix(&ws_root) + .unwrap_or(f) + .to_string_lossy() + .replace('\\', "/"); + let known = CAPSULE_SEAMS + .iter() + .chain(HOST_TOOL_FILES) + .any(|k| rel == *k); + if !known { + unknown.push(rel.clone()); + } + if CAPSULE_SEAMS.contains(&rel.as_str()) { + assert!( + src.contains("RUNTIME_ONLY_SECRETS"), + "capsule spawn seam {rel} no longer references RUNTIME_ONLY_SECRETS — the \ + P16 strip was refactored away" + ); + } + } + assert!( + unknown.is_empty(), + "NEW process-spawn site(s) not classified as capsule-seam or host-tool — route them \ + through a stripping seam or consciously allowlist: {unknown:?}" + ); + } +} diff --git a/elastos/crates/elastos-server/src/api/chain_tx.rs b/elastos/crates/elastos-server/src/api/chain_tx.rs index 7954997d..8ed9ce66 100644 --- a/elastos/crates/elastos-server/src/api/chain_tx.rs +++ b/elastos/crates/elastos-server/src/api/chain_tx.rs @@ -183,6 +183,83 @@ pub(crate) fn block_number_live() -> Result { .ok_or_else(|| format!("chain-provider block_number returned no usable value: {resp}")) } +/// The confirmation state of a broadcast tx, read from its receipt + the chain tip (Sprint 35). +/// The money-critical distinction: only `Confirmed` promotes a pending DRM buy to charged, only +/// `Reverted` refunds it, and `Pending` (not yet mined, below the depth floor, or the RPC was +/// unreachable) leaves the reservation held — NEVER auto-promoted. +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) enum TxConfirmation { + /// The receipt is mined, `status == 0x1` (success), AND at least `min_confirmations` deep. + Confirmed, + /// The receipt is mined and `status == 0x0` (the tx reverted on-chain). + Reverted, + /// Not yet mined, below the depth floor, or the confirmation read failed — hold, do not + /// promote. Carries a human-readable why for the reconciliation log. + Pending(String), +} + +/// Read a broadcast tx's confirmation state via the REAL chain-provider `receipt` op +/// (`eth_getTransactionReceipt`) + the chain tip (`block_number`), applying a depth floor +/// (Sprint 35). READ-ONLY, no keys (P3). Fail-SAFE: any read failure returns `Pending` (the +/// reservation stays held; a not-yet-mined or unreachable tx is NEVER auto-charged). Live Base +/// only — the operator runbook, never CI. +pub(crate) fn tx_confirmation_live( + tx_hash: &str, + min_confirmations: u64, +) -> Result { + let (network, init) = live_chain_init()?; + let chain_bin = resolve_chain_bin(); + let request = json!({ "op": "receipt", "network": network, "hash": tx_hash }); + let resp = run_chain_capsule(&chain_bin, &init, &request)?; + // A null/absent receipt = the tx is not yet mined ⇒ Pending, hold (fail-safe). + let receipt = match resp.get("receipt") { + Some(r) if !r.is_null() => r, + _ => { + return Ok(TxConfirmation::Pending( + "tx not yet mined (no receipt)".to_string(), + )) + } + }; + let tip = block_number_live()?; + Ok(classify_receipt(receipt, tip, min_confirmations)) +} + +/// The PURE, money-critical classification of a mined receipt against the chain tip + depth floor +/// (Sprint 35). Extracted so the fail-closed rules (council S35 guardian F1/F2, red-team F3) are +/// CI-testable without a live chain. Rules, in order: +/// 1. no usable `blockNumber` ⇒ `Pending` (cannot compute depth); +/// 2. depth (`tip - mined + 1`) below the floor ⇒ `Pending` — gates BOTH verdicts, so a shallow +/// revert (which a reorg can re-include successfully) never refunds prematurely; +/// 3. at/above the floor: `status` explicit `0` ⇒ `Reverted`; explicit non-zero ⇒ `Confirmed`; +/// absent/empty/unparseable ⇒ `Pending` (a money gate defaults to HOLD, never "success"). +/// Accepts a hex STRING (`0x1`) or a JSON NUMBER. +fn classify_receipt(receipt: &Value, tip: u64, min_confirmations: u64) -> TxConfirmation { + let mined_block = receipt + .get("blockNumber") + .and_then(Value::as_str) + .and_then(|s| u64::from_str_radix(s.trim_start_matches("0x"), 16).ok()); + let Some(mined_block) = mined_block else { + return TxConfirmation::Pending("receipt has no usable blockNumber".to_string()); + }; + let depth = tip.saturating_sub(mined_block).saturating_add(1); + if depth < min_confirmations { + return TxConfirmation::Pending(format!( + "at depth {depth} of {min_confirmations} required" + )); + } + let status_val = receipt.get("status").and_then(|s| { + s.as_str() + .map(|h| h.trim_start_matches("0x").trim()) + .and_then(|h| u64::from_str_radix(h, 16).ok()) + .or_else(|| s.as_u64()) + }); + match status_val { + Some(0) => TxConfirmation::Reverted, + Some(_) => TxConfirmation::Confirmed, + None => TxConfirmation::Pending("receipt has no parseable success status".to_string()), + } +} + /// Fetch `eth_getLogs` entries via the REAL chain-provider `logs` op (one window; the caller bounds /// the range). READ-ONLY; no keys (P3). Returns the raw log array (empty on no matches). pub(crate) fn get_logs_live(filter: Value) -> Result, String> { @@ -249,3 +326,52 @@ fn mock_tx_word(seed: &Value) -> String { h.update(serde_json::to_string(seed).unwrap_or_default().as_bytes()); format!("0x{}", hex::encode(h.finalize())) } + +#[cfg(test)] +mod confirmation_tests { + use super::*; + + #[test] + fn classify_receipt_is_fail_closed_on_status_and_depth() { + let mined = json!({"status": "0x1", "blockNumber": "0x64"}); // block 100 + // Deep enough + success ⇒ Confirmed. + assert_eq!(classify_receipt(&mined, 102, 3), TxConfirmation::Confirmed); + // Below the depth floor ⇒ Pending (tip 100 == mined ⇒ depth 1 < 3). + assert!(matches!( + classify_receipt(&mined, 100, 3), + TxConfirmation::Pending(_) + )); + // Reverted, deep enough ⇒ Reverted (council S35 guardian F2: depth gates the revert too). + let reverted = json!({"status": "0x0", "blockNumber": "0x64"}); + assert_eq!( + classify_receipt(&reverted, 110, 3), + TxConfirmation::Reverted + ); + // Reverted but SHALLOW ⇒ Pending, NOT an immediate refund. + assert!(matches!( + classify_receipt(&reverted, 100, 3), + TxConfirmation::Pending(_) + )); + // council S35 red-team F3 / guardian F1: a receipt with NO status but a deep block must + // NOT read as success — hold. + let no_status = json!({"blockNumber": "0x64"}); + assert!(matches!( + classify_receipt(&no_status, 999, 3), + TxConfirmation::Pending(_) + )); + // A numeric status is accepted (0 ⇒ revert, 1 ⇒ success). + assert_eq!( + classify_receipt(&json!({"status": 1, "blockNumber": "0x64"}), 999, 3), + TxConfirmation::Confirmed + ); + assert_eq!( + classify_receipt(&json!({"status": 0, "blockNumber": "0x64"}), 999, 3), + TxConfirmation::Reverted + ); + // No blockNumber ⇒ cannot compute depth ⇒ Pending. + assert!(matches!( + classify_receipt(&json!({"status": "0x1"}), 999, 3), + TxConfirmation::Pending(_) + )); + } +} diff --git a/elastos/crates/elastos-server/src/api/erc20_checkout.rs b/elastos/crates/elastos-server/src/api/erc20_checkout.rs new file mode 100644 index 00000000..6e322a11 --- /dev/null +++ b/elastos/crates/elastos-server/src/api/erc20_checkout.rs @@ -0,0 +1,339 @@ +//! The ERC-20 checkout rail (Sprint 48 — Track D2): the SECOND market vertical behind the +//! `PaymentProvider` seam, proving the contract (docs/SPEC-market-provider-v1.md) is not +//! DRM-shaped. An agent pays an arbitrary EVM address in ONE operator-declared ERC-20 under its +//! mandate cap: `runtime.pay { payee: "0x…", amount }` becomes `transfer(payee, amount × +//! ELASTOS_ERC20_SPEND_UNIT)` on the declared token — held `Pending` at broadcast, promoted to +//! charged only after on-chain confirmation (the same chain-settled reconciler spine as the DRM +//! rail), refunded exactly once on revert. +//! +//! MONEY INVARIANTS (the S43 discipline, by construction — the call site decides, not the bytes): +//! - Every failure STRICTLY BEFORE the broadcast op (bad payee address, unit overflow, calldata +//! assembly, the wallet SIGN leg incl. the chain PREPARE read) is `PayError::NotCharged` — +//! provably nothing moved, the cap reservation is refunded. +//! - The broadcast op and everything after is `PayError::Indeterminate` carrying the +//! `erc20:tx=;to=…;amount=…;tok=…` rail_ref — the tx may be out; the reservation is HELD +//! and the reconciler resolves it from the chain receipt. A success return does not exist: +//! like the DRM rail, a broadcast-accepted checkout is NEVER "charged" until confirmed. +//! - `rail()` is `PaymentRail::Erc20` (compiler-forced), so the reconciler selects these pendings +//! by STRUCTURED tag; a hostile HTTP endpoint crafting an `erc20:tx=` note is never polled. +//! +//! SCOPE HONESTY: the live leg signs inside the wallet capsule (managed account), which is a +//! `dev-modes` build capability — a RELEASE build refuses with `NotCharged` (nothing moves). +//! The external-signature checkout flow (release-grade) is a tracked follow-up; the DRM rail has +//! the same posture. Mock settlement (gate tests) requires BOTH `dev-modes` AND the operator's +//! explicit mock-money opt-in at wiring time. + +#[cfg(feature = "dev-modes")] +use serde_json::{json, Value}; +#[cfg(feature = "dev-modes")] +use sha2::{Digest, Sha256}; + +use crate::intent_executor::{PayError, PaymentProvider}; + +/// `transfer(address,uint256)` — the canonical ERC-20 transfer selector. +pub(crate) const ERC20_TRANSFER_SELECTOR: &str = "a9059cbb"; + +/// Normalize an EVM address: `0x` + 40 hex chars, lowercased. Anything else is refused — a payee +/// that is not a real address must fail BEFORE any money moves (P11). +pub(crate) fn normalize_evm_address(raw: &str) -> Result { + let t = raw.trim(); + let hex_part = t + .strip_prefix("0x") + .or_else(|| t.strip_prefix("0X")) + .ok_or_else(|| format!("payee {t:?} is not a 0x-prefixed EVM address"))?; + if hex_part.len() != 40 || !hex_part.chars().all(|c| c.is_ascii_hexdigit()) { + return Err(format!( + "payee {t:?} is not a 40-hex-char EVM address — refusing before any money moves" + )); + } + Ok(format!("0x{}", hex_part.to_ascii_lowercase())) +} + +/// Encode `transfer(to, amount)` calldata. PURE (unit-tested): selector + address word + amount +/// word — the exact bytes the token contract executes, so the encoding invariant can never +/// silently regress. +pub(crate) fn encode_erc20_transfer(to: &str, amount_base: u128) -> Result { + let addr = normalize_evm_address(to)?; + Ok(format!( + "0x{ERC20_TRANSFER_SELECTOR}{:0>64}{:064x}", + addr.trim_start_matches("0x"), + amount_base + )) +} + +/// A deterministic, even-length-hex "signed tx" for the MOCK settlement path (the mock chain +/// never inspects it; it is not a real signature) — mirrors the DRM rail's mock discipline. +#[cfg(feature = "dev-modes")] +fn representative_signed_tx(unsigned: &Value) -> String { + let mut h = Sha256::new(); + h.update(b"elastos-erc20/checkout-mock-signed/v1"); + h.update( + serde_json::to_string(unsigned) + .unwrap_or_default() + .as_bytes(), + ); + format!("0x02{}", hex::encode(h.finalize())) +} + +/// How this provider settles. Selected at WIRING time (not per-pay), like the DRM rail's mode. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Erc20Mode { + /// Mock settlement through the chain-provider's mock broadcast (gate tests / demos). Wired + /// only under `dev-modes` AND the explicit mock-money opt-in — see `build_pay_rail`. + Mock, + /// Live settlement: wallet-capsule managed signing + real broadcast (dev-modes builds; a + /// release build refuses fail-closed — external signing is the tracked follow-up). + Live, +} + +/// The ERC-20 checkout provider — see the module docs for the contract it implements. +/// (`token`/`principal_id` and `rail_ref` are consumed only by the settlement legs, which are +/// `dev-modes`-gated — a release build refuses every pay fail-closed, so the fields are +/// deliberately dead there; council S48 guardian F1.) +#[cfg_attr(not(feature = "dev-modes"), allow(dead_code))] +pub struct Erc20CheckoutProvider { + /// The ONE ERC-20 token this rail pays in (operator-declared; the unit mapping denominates it). + token: String, + /// Token base-units per meter unit (like the DRM `ELASTOS_DRM_SPEND_UNIT`) — REQUIRED ≥ 1 at + /// wiring, so the mandate cap is a literal on-chain ceiling in the declared token. + spend_unit: u128, + /// The managed-account owner for the live sign leg. + principal_id: String, + mode: Erc20Mode, +} + +#[cfg_attr(not(feature = "dev-modes"), allow(dead_code))] +impl Erc20CheckoutProvider { + /// `spend_unit` MUST be ≥ 1 (the wiring refuses to wire otherwise — SPEC §5's "never a + /// silent 1:1" applies to the mapping's DECLARATION, and a 0 here would be a caller bug, not + /// an operator choice). Debug builds assert; release clamps to 1 as a last-resort guard + /// (council S48 guardian F5: documented, not silent). + pub fn new(token: String, spend_unit: u128, principal_id: String, mode: Erc20Mode) -> Self { + debug_assert!( + spend_unit >= 1, + "spend_unit must be >= 1 (wiring refuses 0)" + ); + Self { + token, + spend_unit: spend_unit.max(1), + principal_id, + mode, + } + } + + /// The canonical `rail_ref` for a broadcast checkout: + /// `erc20:tx=;to=;amount=;tok=` — compact, greppable, and + /// delimiter-stripped per component (a hostile field cannot forge the parsed binding), the + /// same discipline as the DRM `rail_ref` (council S34 red-team F3). + fn rail_ref(&self, tx_hash: &str, to: &str, amount_base: u128) -> String { + let clean = |s: &str| s.replace([';', '='], ""); + format!( + "erc20:tx={};to={};amount={amount_base};tok={}", + clean(tx_hash), + clean(to), + clean(&self.token) + ) + } +} + +impl PaymentProvider for Erc20CheckoutProvider { + fn rail(&self) -> crate::payment_ledger::PaymentRail { + // Positively tag checkout pendings so the chain-settled reconciler selects them by this + // structured discriminator (Sprint 44's contract) — never by rail-controlled text. + crate::payment_ledger::PaymentRail::Erc20 + } + + fn pay(&self, payee: &str, amount: u64, _idempotency_key: &str) -> Result { + // ── Every leg here is STRICTLY PRE-BROADCAST ⇒ NotCharged (refund) by construction. ── + let to = normalize_evm_address(payee).map_err(PayError::NotCharged)?; + let amount_base = (amount as u128) + .checked_mul(self.spend_unit) + .ok_or_else(|| { + PayError::NotCharged(format!( + "amount {amount} × unit {} overflows the token amount word — refusing \ + before any money moves", + self.spend_unit + )) + })?; + let data = encode_erc20_transfer(&to, amount_base).map_err(PayError::NotCharged)?; + // In a release build both settlement arms refuse before using the calldata — the encode + // still runs (it is the payee/amount VALIDATION), but `data` itself goes unused there. + #[cfg(not(feature = "dev-modes"))] + let _ = &data; + + match self.mode { + Erc20Mode::Mock => { + #[cfg(feature = "dev-modes")] + { + let unsigned = json!({ "to": self.token, "value": "0x0", "data": data }); + let signed = representative_signed_tx(&unsigned); + // ── The broadcast op and after ⇒ Indeterminate (HELD) by construction. ── + let tx_hash = super::chain_tx::broadcast_signed_mock(&unsigned, &signed) + .map_err(PayError::Indeterminate)?; + Err(PayError::Indeterminate(self.rail_ref( + &tx_hash, + &to, + amount_base, + ))) + } + #[cfg(not(feature = "dev-modes"))] + { + Err(PayError::NotCharged( + "mock ERC-20 settlement is a dev-modes build capability — nothing moved" + .to_string(), + )) + } + } + Erc20Mode::Live => { + #[cfg(feature = "dev-modes")] + { + // SIGN leg (incl. the chain PREPARE read inside the closure) runs strictly + // BEFORE broadcast ⇒ a failure here is provably pre-broadcast (the S43/S46 + // discipline; the prepare-deadline refund ratchet covers this call shape). + let chain_id = crate::api::buy_authority::chain_id_default(); + let token = self.token.clone(); + let sig = super::wallet_signer::sign_with_managed_account( + &self.principal_id, + chain_id, + |from| super::chain_tx::prepare_intent_live(from, &token, "0x0", &data), + ) + .map_err(PayError::NotCharged)?; + // ── The broadcast op and after ⇒ Indeterminate (HELD) by construction. ── + let tx_hash = super::chain_tx::broadcast_signed_live(&sig.signed_transaction) + .map_err(PayError::Indeterminate)?; + Err(PayError::Indeterminate(self.rail_ref( + &tx_hash, + &to, + amount_base, + ))) + } + #[cfg(not(feature = "dev-modes"))] + { + Err(PayError::NotCharged( + "live ERC-20 checkout signs in the wallet capsule (managed account), a \ + dev-modes build capability; the external-signature checkout flow is a \ + tracked follow-up — nothing moved (fail-closed)" + .to_string(), + )) + } + } + } + } +} + +/// The chain-confirmation reader for checkout pendings — the same receipt + depth-floor logic as +/// the DRM rail (one confirmation discipline, P5), so the in-runtime scheduler polls +/// `erc20:tx=` pendings exactly like `drm:tx=` ones. +impl crate::drm_marketplace::DrmConfirmer for Erc20CheckoutProvider { + fn confirm(&self, tx_hash: &str) -> crate::drm_marketplace::DrmConfirmation { + crate::drm_marketplace::confirm_chain_tx(tx_hash) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + const PAYEE: &str = "0x34DAf31b99b5A59CEB18e424dbC112FA6E5F3dc3"; + + #[test] + fn transfer_calldata_encodes_selector_address_and_amount_words() { + let data = encode_erc20_transfer(PAYEE, 1_000_000).expect("valid encode"); + let body = data.strip_prefix("0x").unwrap(); + assert_eq!(&body[..8], ERC20_TRANSFER_SELECTOR); + assert_eq!(body.len(), 8 + 64 + 64, "selector + two ABI words"); + assert_eq!( + &body[8..72], + format!("{:0>64}", PAYEE[2..].to_ascii_lowercase()), + "address word, left-padded, lowercased" + ); + assert_eq!( + &body[72..], + format!("{:064x}", 1_000_000u128), + "amount word" + ); + } + + #[test] + fn junk_payees_are_refused_before_any_money_moves() { + for junk in [ + "QmNotAnAddress", + "0x1234", // too short + "0x34daf31b99b5a59ceb18e424dbc112fa6e5f3dc3ff", // too long + "0xZZZZf31b99b5a59ceb18e424dbc112fa6e5f3dc3", // non-hex + "", + ] { + assert!(normalize_evm_address(junk).is_err(), "must refuse {junk:?}"); + } + // The provider maps that refusal to NotCharged (refund) — pre-broadcast by construction. + let p = Erc20CheckoutProvider::new( + "0x1111111111111111111111111111111111111111".into(), + 1_000_000, + "did:test:payer".into(), + Erc20Mode::Mock, + ); + match p.pay("not-an-address", 5, "flint-k") { + Err(PayError::NotCharged(_)) => {} + other => panic!("junk payee must be NotCharged, got {other:?}"), + } + } + + #[test] + fn a_unit_overflow_is_refused_before_any_money_moves() { + let p = Erc20CheckoutProvider::new( + "0x1111111111111111111111111111111111111111".into(), + u128::MAX, + "did:test:payer".into(), + Erc20Mode::Mock, + ); + match p.pay(PAYEE, 2, "flint-k") { + Err(PayError::NotCharged(why)) => { + assert!(why.contains("overflow"), "names the refusal: {why}") + } + other => panic!("overflow must be NotCharged, got {other:?}"), + } + } + + /// The vertical's own money ratchet (mirrors the DRM rail's): a broadcast-ACCEPTED checkout + /// is NEVER charged at broadcast — it is `Indeterminate`, HELD, carrying a parseable + /// `erc20:tx=` rail_ref the chain-settled reconciler can poll. + #[test] + #[cfg(all(unix, feature = "dev-modes"))] + fn a_broadcast_checkout_is_held_indeterminate_with_a_parseable_rail_ref() { + let _g = crate::api::ddrm_env_lock(); + let dir = tempfile::tempdir().unwrap(); + let stub = dir.path().join("ok-broadcast.sh"); + std::fs::write( + &stub, + "#!/bin/sh\nread _i\nprintf '{\"status\":\"ok\",\"data\":{}}\\n'\nread _o\nprintf \ + '{\"status\":\"ok\",\"data\":{\"transaction_hash\":\"0xfeedbeef\"}}\\n'\n", + ) + .unwrap(); + use std::os::unix::fs::PermissionsExt as _; + std::fs::set_permissions(&stub, std::fs::Permissions::from_mode(0o755)).unwrap(); + std::env::set_var("ELASTOS_CHAIN_PROVIDER_BIN", &stub); + + let p = Erc20CheckoutProvider::new( + "0x1111111111111111111111111111111111111111".into(), + 1_000_000, + "did:test:payer".into(), + Erc20Mode::Mock, + ); + let out = p.pay(PAYEE, 3, "flint-k"); + std::env::remove_var("ELASTOS_CHAIN_PROVIDER_BIN"); + + match out { + Err(PayError::Indeterminate(rail_ref)) => { + assert!( + rail_ref.starts_with("erc20:tx=0xfeedbeef;"), + "parseable chain-settled rail_ref: {rail_ref}" + ); + assert!( + rail_ref.contains(";amount=3000000;"), + "amount in token base units (3 × 1_000_000): {rail_ref}" + ); + } + other => panic!("a broadcast checkout must be HELD Indeterminate, got {other:?}"), + } + } +} diff --git a/elastos/crates/elastos-server/src/api/gateway.rs b/elastos/crates/elastos-server/src/api/gateway.rs index de1888bf..2eb077db 100644 --- a/elastos/crates/elastos-server/src/api/gateway.rs +++ b/elastos/crates/elastos-server/src/api/gateway.rs @@ -54,6 +54,8 @@ mod gateway_home_token; mod gateway_inbox; #[path = "gateway_inspect_actions.rs"] mod gateway_inspect_actions; +#[path = "gateway_mandates.rs"] +mod gateway_mandates; #[path = "gateway_marketplace.rs"] mod gateway_marketplace; #[path = "gateway_provider_proxy.rs"] @@ -78,9 +80,9 @@ pub(super) use gateway_home_token::{ home_session_cookie_header_for_token, issue_home_launch_token_for_auth_grant, issue_home_launch_token_with_context, require_fresh_passkey_home_token, require_home_launch_token, require_home_launch_token_context, - require_home_launch_token_for_any, require_home_launch_token_for_any_app_context, - require_home_launch_token_for_any_context, require_home_token, require_home_token_context, - HomeLaunchTokenContext, + require_home_launch_token_context_transport, require_home_launch_token_for_any, + require_home_launch_token_for_any_app_context, require_home_launch_token_for_any_context, + require_home_token, require_home_token_context, HomeLaunchTokenContext, }; #[cfg(test)] use gateway_home_token::{ @@ -195,6 +197,12 @@ const WALLET_PRICE_IDS: &[(&str, &str)] = &[ pub(crate) const ROOM_SESSION_COOKIE: &str = "room-session"; pub(crate) const BROWSER_SESSION_COOKIE: &str = "browser-session"; pub(crate) const HOME_SESSION_COOKIE: &str = "home-session"; +/// The mandates app's launch-token cookie (Sprint 33): HttpOnly, SameSite=Strict, and +/// path-scoped to [`MANDATES_API_COOKIE_PATH`] so it rides ONLY the mandates API — the money +/// surface's launch credential never appears in a URL. +pub(crate) const MANDATES_SESSION_COOKIE: &str = "mandates-session"; +/// The path scope for [`MANDATES_SESSION_COOKIE`] — the mandates sub-router's API prefix. +pub(crate) const MANDATES_API_COOKIE_PATH: &str = "/api/apps/mandates"; const ROOM_SYNC_CONSUMER_ID: &str = "room-sync"; const HOME_LAUNCH_TOKEN_DOMAIN: &str = "elastos.home.launch.v1"; const HOME_LAUNCH_TOKEN_TTL_SECS: u64 = 12 * 60 * 60; @@ -312,13 +320,24 @@ impl GatewayState { if let Some(existing) = self.audit_log.get() { return Ok(existing.clone()); } + // Serialize CONSTRUCTION (S52): the audit log now holds a single-opener flock, so the old + // benign both-construct-one-wins race would make the LOSER's open fail `WouldBlock` and + // surface a spurious error while a healthy canonical log exists. One constructor runs; + // everyone else re-reads the cell. A process-global mutex is fine — construction happens + // once per gateway lifetime (tests with distinct data_dirs serialize briefly, harmlessly). + static CONSTRUCT: std::sync::Mutex<()> = std::sync::Mutex::new(()); + let _guard = CONSTRUCT + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + if let Some(existing) = self.audit_log.get() { + return Ok(existing.clone()); + } let path = self.data_dir.join("audit").join("gateway-audit.log"); let log = Arc::new( AuditLog::with_file(&path) .map_err(|e| format!("gateway audit log unavailable at {path:?}: {e}"))?, ); let _ = self.audit_log.set(log.clone()); - // Another thread may have won the race; return whatever is now canonical. Ok(self.audit_log.get().cloned().unwrap_or(log)) } diff --git a/elastos/crates/elastos-server/src/api/gateway_capsule_catalog.rs b/elastos/crates/elastos-server/src/api/gateway_capsule_catalog.rs index 8b3d516a..e4bccca1 100644 --- a/elastos/crates/elastos-server/src/api/gateway_capsule_catalog.rs +++ b/elastos/crates/elastos-server/src/api/gateway_capsule_catalog.rs @@ -101,25 +101,28 @@ pub(super) async fn capsule_interface_invoke( ); } + let secure = request_uses_tls(&headers); let output = match enforce_affordance_invocation_policy(&resolved) { - Ok(()) => match dispatch_capsule_affordance(&state, &context, &resolved, &request).await { - Ok(output) => output, - Err((status, code, message)) => { - let _ = append_provider_effect_audit( - &state.data_dir, - ProviderEffectAuditInput { - capsule_id: &resolved.capsule, - event_type: "capsule.affordance.failed", - principal_id: &context.principal_id, - session_id: &context.session_id, - request_id: &request_id, - result: "failed", - reason: &message, - }, - ); - return capsule_invoke_error(&resolved, status, code, &message); + Ok(()) => { + match dispatch_capsule_affordance(&state, &context, &resolved, &request, secure).await { + Ok(output) => output, + Err((status, code, message)) => { + let _ = append_provider_effect_audit( + &state.data_dir, + ProviderEffectAuditInput { + capsule_id: &resolved.capsule, + event_type: "capsule.affordance.failed", + principal_id: &context.principal_id, + session_id: &context.session_id, + request_id: &request_id, + result: "failed", + reason: &message, + }, + ); + return capsule_invoke_error(&resolved, status, code, &message); + } } - }, + } Err((status, code, message)) => { let _ = append_provider_effect_audit( &state.data_dir, @@ -157,16 +160,24 @@ pub(super) async fn capsule_interface_invoke( ); } - Json(CapsuleInterfaceInvokeResponse { + let mut response = Json(CapsuleInterfaceInvokeResponse { schema: CAPSULE_INTERFACE_INVOKE_RESULT_SCHEMA.to_string(), status: "ok".to_string(), capsule: resolved.capsule, interface: resolved.interface_id, method: resolved.method.id, request_id, - output, + output: output.value, }) - .into_response() + .into_response(); + // Cookie-delivered launch targets (the money surface, Sprint 33): the launch token rides an + // HttpOnly Set-Cookie on this response instead of the returned route. + if let Some(cookie) = output.set_cookie { + response + .headers_mut() + .append(axum::http::header::SET_COOKIE, cookie); + } + response } pub(super) fn require_capsule_catalog_token( @@ -351,18 +362,37 @@ fn enforce_affordance_invocation_policy( Ok(()) } +/// An affordance's JSON output plus, for launch targets whose token is cookie-delivered (the +/// money surface, Sprint 33), the Set-Cookie header the invoke RESPONSE must carry. +struct CapsuleAffordanceOutput { + value: serde_json::Value, + set_cookie: Option, +} + +impl CapsuleAffordanceOutput { + fn value(value: serde_json::Value) -> Self { + Self { + value, + set_cookie: None, + } + } +} + async fn dispatch_capsule_affordance( state: &GatewayState, context: &HomeLaunchTokenContext, resolved: &ResolvedCapsuleAffordance, request: &CapsuleInterfaceInvokeRequest, -) -> Result { + secure: bool, +) -> Result { let resource = resolved.method.resource.as_deref().unwrap_or_default(); let operation = resolved.method.operation.as_deref().unwrap_or_default(); match (resource, operation) { ("elastos://capsules/*", "list") => { serde_json::to_value(capsule_catalog_summary(&state.data_dir)) - .map(|catalog| serde_json::json!({ "catalog": catalog })) + .map(|catalog| { + CapsuleAffordanceOutput::value(serde_json::json!({ "catalog": catalog })) + }) .map_err(|err| { ( StatusCode::INTERNAL_SERVER_ERROR, @@ -372,7 +402,7 @@ async fn dispatch_capsule_affordance( }) } ("elastos://capsules/*", "launch") => { - dispatch_capsule_launch_affordance(state, context, request).await + dispatch_capsule_launch_affordance(state, context, request, secure).await } _ => Err(( StatusCode::NOT_IMPLEMENTED, @@ -389,7 +419,8 @@ async fn dispatch_capsule_launch_affordance( state: &GatewayState, context: &HomeLaunchTokenContext, request: &CapsuleInterfaceInvokeRequest, -) -> Result { + secure: bool, +) -> Result { let target = request .input .get("target") @@ -438,12 +469,13 @@ async fn dispatch_capsule_launch_affordance( let launch = launch_runtime_backed_home_target(&state.data_dir, target_summary.target.as_str(), context) .await; - let route = append_home_launch_token( + let delivery = append_home_launch_token( &state.data_dir, &target_summary.route, target_summary.target.as_str(), &BTreeMap::new(), context, + secure, ) .map_err(|err| { ( @@ -453,17 +485,20 @@ async fn dispatch_capsule_launch_affordance( ) })?; - Ok(serde_json::json!({ - "target": target_summary.target, - "title": target_summary.title, - "route": route, - "attach_kind": target_summary.attach_kind, - "role": target_summary.role, - "target_kind": target_summary.target_kind, - "launch_status": launch.as_ref().map(|summary| summary.status.clone()), - "launch_detail": launch.as_ref().and_then(|summary| summary.detail.clone()), - "capsule_id": launch.and_then(|summary| summary.capsule_id), - })) + Ok(CapsuleAffordanceOutput { + value: serde_json::json!({ + "target": target_summary.target, + "title": target_summary.title, + "route": delivery.route, + "attach_kind": target_summary.attach_kind, + "role": target_summary.role, + "target_kind": target_summary.target_kind, + "launch_status": launch.as_ref().map(|summary| summary.status.clone()), + "launch_detail": launch.as_ref().and_then(|summary| summary.detail.clone()), + "capsule_id": launch.and_then(|summary| summary.capsule_id), + }), + set_cookie: delivery.set_cookie, + }) } fn capsule_invoke_error( diff --git a/elastos/crates/elastos-server/src/api/gateway_home_runtime.rs b/elastos/crates/elastos-server/src/api/gateway_home_runtime.rs index 4dae3cbc..3fbdb8a6 100644 --- a/elastos/crates/elastos-server/src/api/gateway_home_runtime.rs +++ b/elastos/crates/elastos-server/src/api/gateway_home_runtime.rs @@ -4,7 +4,7 @@ pub(super) async fn home_launch( State(state): State, headers: HeaderMap, Json(req): Json, -) -> Result, (StatusCode, Json)> { +) -> Result)> { let context = require_home_token_context(&state.data_dir, &headers).map_err(|err| { ( StatusCode::FORBIDDEN, @@ -46,26 +46,53 @@ pub(super) async fn home_launch( &context, ) .await; - let route = append_home_launch_token( + let delivery = append_home_launch_token( &state.data_dir, &target_summary.route, target_summary.target.as_str(), &req.query, &context, + request_uses_tls(&headers), ) .map_err(gateway_internal_error)?; - Ok(Json(HomeLaunchResponse { + let mut response = Json(HomeLaunchResponse { target: target_summary.target, title: target_summary.title, - route, + route: delivery.route, attach_kind: target_summary.attach_kind, role: target_summary.role, target_kind: target_summary.target_kind, launch_status: launch.as_ref().map(|summary| summary.status.clone()), launch_detail: launch.as_ref().and_then(|summary| summary.detail.clone()), capsule_id: launch.and_then(|summary| summary.capsule_id), - })) + }) + .into_response(); + // Cookie-delivered targets (the money surface): the launch token rides an HttpOnly Set-Cookie + // on THIS response — the same-origin shell fetch stores it in the browser jar, and the app's + // path-scoped API calls carry it from there. The URL above holds no credential. + if let Some(cookie) = delivery.set_cookie { + response + .headers_mut() + .append(axum::http::header::SET_COOKIE, cookie); + } + Ok(response) +} + +/// A launched app route plus, for cookie-delivered targets, the Set-Cookie header the launch +/// RESPONSE must carry. For every ordinary app `set_cookie` is `None` and the token rides the +/// URL exactly as before Sprint 33. +pub(super) struct HomeLaunchRouteDelivery { + pub(super) route: String, + pub(super) set_cookie: Option, +} + +/// True for targets whose launch token is COOKIE-delivered instead of URL-borne. Today that is +/// exactly the mandates app — the surface carrying money verbs (Sprint 33, council S31 F1): its +/// launch URL must never contain the bearer credential (URLs are logged, copyable, and readable +/// by frame script; an HttpOnly cookie is none of those). +pub(super) fn is_cookie_delivered_target(target: &str) -> bool { + target == super::gateway_mandates::MANDATES_CAPSULE_ID } pub(super) fn append_home_launch_token( @@ -74,20 +101,43 @@ pub(super) fn append_home_launch_token( target: &str, query: &BTreeMap, context: &HomeLaunchTokenContext, -) -> anyhow::Result { + secure: bool, +) -> anyhow::Result { let token = issue_home_launch_token_with_context(data_dir, target, context)?; + let cookie_delivered = is_cookie_delivered_target(target); let mut serializer = form_urlencoded::Serializer::new(String::new()); - serializer.append_pair("home_token", &token); + if cookie_delivered { + // No bearer credential in the URL — only the non-secret in-shell marker the app uses to + // distinguish "launched by the shell" from "opened standalone" (its sample mode). + serializer.append_pair("shell", "1"); + } else { + serializer.append_pair("home_token", &token); + } for (key, value) in query { let key = key.trim(); - if key.is_empty() || key == "home_token" { + if key.is_empty() || key == "home_token" || (cookie_delivered && key == "shell") { continue; } serializer.append_pair(key, value); } let encoded = serializer.finish(); let separator = if route.contains('?') { '&' } else { '?' }; - Ok(format!("{route}{separator}{encoded}")) + let set_cookie = if cookie_delivered { + Some( + super::gateway_home_token::app_launch_cookie_header_for_token( + MANDATES_SESSION_COOKIE, + &token, + MANDATES_API_COOKIE_PATH, + secure, + )?, + ) + } else { + None + }; + Ok(HomeLaunchRouteDelivery { + route: format!("{route}{separator}{encoded}"), + set_cookie, + }) } pub(super) fn home_targets(data_dir: &std::path::Path) -> Vec { @@ -1614,14 +1664,20 @@ mod tests { query.insert("home_token".to_string(), "attacker".to_string()); query.insert("capsule".to_string(), "documents".to_string()); - let route = append_home_launch_token( + let delivery = append_home_launch_token( dir.path(), "/apps/documents/", "documents", &query, &context, + false, ) .unwrap(); + assert!( + delivery.set_cookie.is_none(), + "ordinary apps keep URL delivery" + ); + let route = delivery.route; let parsed = url::Url::parse(&format!("http://localhost{route}")).unwrap(); let query_pairs = parsed.query_pairs().collect::>(); let home_tokens = query_pairs @@ -1635,4 +1691,83 @@ mod tests { .iter() .any(|(key, value)| key == "capsule" && value == "documents")); } + + /// Sprint 33 ratchet (council S31 F1): the MANDATES launch URL carries NO bearer credential — + /// the token rides an HttpOnly, SameSite=Strict, path-scoped Set-Cookie instead, and the URL + /// keeps only the non-secret `shell=1` in-shell marker. Before this sprint the exact failure + /// was `/apps/mandates/?home_token=<12h bearer token>` — copyable from history, logs, and + /// frame script. + #[test] + fn mandates_launch_url_carries_no_token_and_the_cookie_carries_it_instead() { + let dir = tempfile::tempdir().unwrap(); + let context = local_home_launch_token_context(dir.path()).unwrap(); + let mut query = BTreeMap::new(); + // A smuggled marker/token in the incoming query must not survive either. + query.insert("home_token".to_string(), "attacker".to_string()); + query.insert("shell".to_string(), "attacker".to_string()); + + let delivery = append_home_launch_token( + dir.path(), + "/apps/mandates/", + super::super::gateway_mandates::MANDATES_CAPSULE_ID, + &query, + &context, + true, + ) + .unwrap(); + + assert!( + !delivery.route.contains("home_token"), + "the money surface's launch URL must never carry the bearer token: {}", + delivery.route + ); + let parsed = url::Url::parse(&format!("http://localhost{}", delivery.route)).unwrap(); + let shell_markers: Vec<_> = parsed + .query_pairs() + .filter(|(key, _)| key == "shell") + .collect(); + assert_eq!(shell_markers.len(), 1, "exactly one in-shell marker"); + assert_eq!( + shell_markers[0].1.as_ref(), + "1", + "the smuggled marker is dropped" + ); + + let cookie = delivery + .set_cookie + .expect("the launch response must deliver the token via Set-Cookie"); + let cookie = cookie.to_str().unwrap(); + assert!(cookie.starts_with(&format!("{MANDATES_SESSION_COOKIE}="))); + assert!( + cookie.contains("HttpOnly"), + "frame script must not read it: {cookie}" + ); + assert!( + cookie.contains("SameSite=Strict"), + "never sent cross-site: {cookie}" + ); + assert!( + cookie.contains(&format!("Path={MANDATES_API_COOKIE_PATH}")), + "scoped to the mandates API alone: {cookie}" + ); + assert!( + cookie.contains("Secure"), + "TLS launches set Secure: {cookie}" + ); + // The cookie value IS a valid launch token for the mandates app. + let token = cookie + .split(';') + .next() + .unwrap() + .trim_start_matches(&format!("{MANDATES_SESSION_COOKIE}=")) + .to_string(); + let mut headers = HeaderMap::new(); + headers.insert("x-elastos-home-token", token.parse().unwrap()); + super::super::require_home_launch_token( + dir.path(), + &headers, + super::super::gateway_mandates::MANDATES_CAPSULE_ID, + ) + .expect("the cookie-delivered token authorizes the mandates surface"); + } } diff --git a/elastos/crates/elastos-server/src/api/gateway_home_token.rs b/elastos/crates/elastos-server/src/api/gateway_home_token.rs index 4f5eb4a9..532acca3 100644 --- a/elastos/crates/elastos-server/src/api/gateway_home_token.rs +++ b/elastos/crates/elastos-server/src/api/gateway_home_token.rs @@ -34,9 +34,21 @@ struct HomeLaunchTokenEnvelope { signer_did: String, } +/// How the launch token reached the gate. The CSRF analysis differs: a HEADER-borne token is +/// unforgeable cross-origin (custom headers force a CORS preflight the gateway never grants to +/// a foreign origin — pinned by the S31 no-ACAO regression test), +/// while a COOKIE-borne token rides ambient browser credentials — cookie-authorized WRITES must +/// therefore also present the surface's custom marker header (see `gateway_mandates`). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) enum HomeTokenTransport { + Header, + Cookie, +} + struct RequiredHomeLaunchToken { app: String, context: HomeLaunchTokenContext, + transport: HomeTokenTransport, } pub(crate) fn home_session_cookie_header_for_token( @@ -70,14 +82,48 @@ fn home_launch_cookie_header( path: &str, secure: bool, ) -> anyhow::Result { - let mut value = - format!("{name}={token}; Max-Age={max_age_secs}; Path={path}; HttpOnly; SameSite=Lax"); + home_launch_cookie_header_same_site(name, token, max_age_secs, path, secure, "Lax") +} + +fn home_launch_cookie_header_same_site( + name: &str, + token: &str, + max_age_secs: u64, + path: &str, + secure: bool, + same_site: &str, +) -> anyhow::Result { + let mut value = format!( + "{name}={token}; Max-Age={max_age_secs}; Path={path}; HttpOnly; SameSite={same_site}" + ); if secure { value.push_str("; Secure"); } HeaderValue::from_str(&value).map_err(|err| anyhow::anyhow!("invalid Set-Cookie header: {err}")) } +/// The Set-Cookie header for an APP-scoped launch-token cookie (Sprint 33, the money surface): +/// `HttpOnly` (an XSS in the frame can still ride it same-origin but can never EXFILTRATE it), +/// `SameSite=Strict` (never sent on any cross-site request), and `Path`-scoped to the one app's +/// API prefix so it rides nothing else. This replaces the URL-borne `?home_token=…` delivery for +/// surfaces that carry money verbs — a launch URL is copyable, logged, and shoulder-surfable; an +/// HttpOnly cookie is none of those. +pub(crate) fn app_launch_cookie_header_for_token( + name: &str, + token: &str, + path: &str, + secure: bool, +) -> anyhow::Result { + home_launch_cookie_header_same_site( + name, + token, + HOME_LAUNCH_TOKEN_TTL_SECS, + path, + secure, + "Strict", + ) +} + #[cfg(test)] pub(crate) fn local_home_launch_token_context( data_dir: &std::path::Path, @@ -208,12 +254,37 @@ pub(crate) fn require_home_launch_token_for_any_app_context( .map(|required| (required.app, required.context)) } +/// The cookie-accepting per-app gate (Sprint 33): validates exactly like +/// [`require_home_launch_token_context`] but ALSO accepts the token from the named HttpOnly +/// cookie, and reports WHICH transport carried it so write routes can demand the anti-CSRF +/// marker header on cookie-authorized requests (a cookie is ambient; a custom header is not). +/// The explicit header wins when both are present. +pub(crate) fn require_home_launch_token_context_transport( + data_dir: &std::path::Path, + headers: &HeaderMap, + expected_app: &str, + cookie_name: &str, +) -> anyhow::Result<(HomeLaunchTokenContext, HomeTokenTransport)> { + require_home_launch_token_for_any_from(data_dir, headers, &[expected_app], Some(cookie_name)) + .map(|required| (required.context, required.transport)) +} + +/// Validates a FRESH, proof-bound (passkey) Home token against the standing context and returns +/// the CANONICAL payload JSON the signature was verified over — the assertion's identity. +/// +/// Callers that must make the assertion SINGLE-USE (the money writes, council S33 F1) MUST key +/// their spent-guard on this returned canonical form, never on the raw token string: signature +/// verification re-parses the envelope and canonicalizes the payload, so the SAME assertion can +/// be re-encoded into byte-different token strings (whitespace, field order) that all still +/// verify — a raw-string key would see each re-encoding as unspent. The canonical payload is +/// what the ed25519 signature actually covers, so every valid re-encoding collapses onto one +/// key, and altering any field to get a new key breaks the signature. pub(crate) fn require_fresh_passkey_home_token( data_dir: &std::path::Path, token: &str, expected_context: &HomeLaunchTokenContext, max_age_secs: u64, -) -> anyhow::Result<()> { +) -> anyhow::Result { let token = token.trim(); if token.is_empty() { anyhow::bail!("missing fresh passkey token"); @@ -263,7 +334,10 @@ pub(crate) fn require_fresh_passkey_home_token( { anyhow::bail!("fresh passkey token authority context mismatch"); } - Ok(()) + // The canonical form the signature covers — the assertion's ONE identity across every + // possible re-encoding of the token string (see the doc-comment). + serde_json::to_string(&serde_json::to_value(&envelope.payload)?) + .map_err(|err| anyhow::anyhow!("could not canonicalize fresh passkey token: {err}")) } pub(crate) fn require_home_token( @@ -328,9 +402,13 @@ fn require_home_launch_token_for_any_from_expected_did( expected_did: String, auth_data_dir: &std::path::Path, ) -> anyhow::Result { - let token = home_launch_token_header(headers) - .or_else(|| cookie_name.and_then(|name| cookie_value_from_headers(headers, name))) - .ok_or_else(|| anyhow::anyhow!("missing home launch token"))?; + let (token, transport) = match home_launch_token_header(headers) { + Some(token) => (token, HomeTokenTransport::Header), + None => cookie_name + .and_then(|name| cookie_value_from_headers(headers, name)) + .map(|token| (token, HomeTokenTransport::Cookie)) + .ok_or_else(|| anyhow::anyhow!("missing home launch token"))?, + }; let bytes = base64::engine::general_purpose::URL_SAFE_NO_PAD .decode(token.as_str()) .map_err(|_| anyhow::anyhow!("invalid home launch token encoding"))?; @@ -378,6 +456,7 @@ fn require_home_launch_token_for_any_from_expected_did( proof_binding_id: envelope.payload.proof_binding_id, grant_id: envelope.payload.grant_id, }, + transport, }) } diff --git a/elastos/crates/elastos-server/src/api/gateway_mandates.rs b/elastos/crates/elastos-server/src/api/gateway_mandates.rs new file mode 100644 index 00000000..d3e2f79f --- /dev/null +++ b/elastos/crates/elastos-server/src/api/gateway_mandates.rs @@ -0,0 +1,2599 @@ +//! The mandates surface for the ElastOS home gateway: list, receipt, revoke, issue. +//! +//! The `mandates` capsule (see `capsules/mandates/`) opens as an app window in the existing +//! shell. It needs LIVE mandate data, and the gateway is the surface the shell talks to. But the +//! standing-grant registry and the durable audit chain live on the API server's +//! [`crate::api::handlers::capability::CapabilityState`], not on the gateway's `GatewayState`. +//! +//! Rather than churn the ~40 `GatewayState` construction sites, this module is a small axum +//! sub-router carrying its own [`MandateApiState`]. The serve path hoists ONE shared +//! `standing_service` + `capability_manager` into [`crate::server_infra::ServerInfrastructure`] and +//! hands the SAME handles to both the API server and (via the supervisor) this sub-router — so the +//! shell reads exactly the registry the API server issues mandates into. The router is merged into +//! the gateway only when both handles are present (see [`super::gateway_server::start_gateway_server`]). +//! +//! Every route is gated by the same home-launch token as every other shell app — the mandates app +//! must be the launched capsule. The GET routes (list, agent-state, receipt, money, marketplace) are strictly read-only. The surface carries +//! FOUR mutations (Sprint 31 count — this enumeration is the surface's security story and must +//! stay literally true, council S31 G-F2): +//! +//! - REVOKE — the kill switch, fail-safe: only ever REMOVES authority (P11/P16). +//! - ISSUE (Sprint 15) — mints a mandate. Authority-GRANTING, so the trust argument is explicit: +//! the home-launch token is minted by the runtime's own signing key when the SHELL launches the +//! app, and the shell is already the runtime's grant root (G-M3 — the shell can issue any +//! mandate anyway). This surface deliberately NARROWS itself below the raw API, server-side +//! (no admin mints, bound-key required), because the residual threat is an XSS in the frame +//! holding the in-URL token. +//! - SPEND-BUDGET (Sprint 31) — provisions a MONEY cap. Same G-M3 tier argument as issue, and the +//! SAME narrowing discipline: the web surface enforces a CAP CEILING server-side +//! ([`WEB_MAX_SPEND_CAP`], overridable via `ELASTOS_WEB_MAX_SPEND_CAP`) — an XSS in the frame +//! cannot provision an unbounded cap; larger caps are a deliberate CLI/consent-broker act. +//! - PAYMENTS/RECONCILE (Sprint 31) — asserts the rail's verdict on ONE indeterminate payment. +//! Same tier: a false "not charged" is a shell-root-level act (the shell can already raise any +//! cap), single-shot by construction (the ledger resolves exactly once), chain-attested, and +//! bounded per entry by the entry's own amount. No web-own narrowing beyond the shared core's +//! guards — the verdict is exactly as dangerous as the cap raise it substitutes for, and +//! ceiling-style bounds don't apply to a boolean. +//! +//! SPRINT 33 (folds council S31 red-team F1) — the money-authorization perimeter: +//! +//! 1. **The launch token is no longer URL-borne.** The shell launch response delivers it via an +//! HttpOnly, SameSite=Strict Set-Cookie path-scoped to this sub-router's API prefix +//! ([`MANDATES_SESSION_COOKIE`]); the launch URL carries only a non-secret `shell=1` marker. +//! Frame script can no longer READ the credential (an XSS can still ride it same-origin — +//! that is what the server-side narrowings above bound — but can never exfiltrate it), and it +//! no longer leaks through history/logs/copy-paste. The gate still accepts the explicit +//! header (tests, tools, pre-S33 clients). Cookie-authorized WRITES must also carry +//! [`MANDATES_APP_MARKER_HEADER`] — a cookie is ambient browser state, and a cross-site page +//! cannot set a custom header without a CORS preflight the gateway never grants to a +//! foreign origin (the mandates routes emit no ACAO — pinned by the S31 regression test). +//! 2. **Money writes require a FRESH passkey verification, spent on use.** SPEND-BUDGET and +//! RECONCILE additionally demand a proof-bound Home token minted by a WebAuthn ceremony at +//! most [`MONEY_FRESH_WINDOW_SECS`] ago for the same principal (the wallet-send gate), and +//! each verification authorizes exactly ONE money write — single-use consumption; replaying +//! it on the same or the other money verb is refused. A leaked standing token or a ridden +//! session can no longer move money. The honest claim (P12) is exactly "THIS operator's +//! authenticator freshly approved ONE money write", nothing more. ISSUE and REVOKE keep the +//! S15/S13 posture deliberately: revoke only ever REMOVES authority and must stay +//! low-friction (it is the kill switch); issue's blast radius is bounded by the mint +//! narrowings; extending fresh-binding to issue is a tracked follow-on (KNOWN_GAPS G-M9), +//! not an oversight. +//! +//! RESIDUAL (KNOWN_GAPS G-M9): the spent-token guard is in-memory (a restart inside the ~3-min +//! freshness window could admit one replay), and the operator/local no-passkey posture cannot +//! make WEB money writes at all — the CLI/consent-broker API is that posture's money path +//! (fail closed; the panel says so). +//! +//! ISSUE delegates to the SAME shared mint path with every fail-closed guard intact (action +//! whitelist, non-empty methods, AUD-5 overbroad-wildcard refusal, agent-key validation, +//! durable-before-visible issuance); the money verbs delegate to the shared +//! `set_spend_budget_core` / `reconcile_payment_core` for the same no-drift reason. +//! +//! All three verbs delegate to the API server's own shared helpers +//! ([`mandate_cards`](crate::api::handlers::capability::mandate_cards), +//! [`revoke_mandate`](crate::api::handlers::capability::revoke_mandate), +//! [`issue_mandate`](crate::api::handlers::capability::issue_mandate)) so neither the liveness +//! invariant, the fail-closed revoke order, nor the mint guards can drift between surfaces (P12: +//! one honest source of truth; a revoked mandate never renders "Live"; a mandate that cannot be +//! durably recorded is not issued). + +use super::*; + +use elastos_runtime::capability::token::TokenId; +use elastos_runtime::capability::CapabilityManager; +use std::path::PathBuf; + +/// State for the read-only mandates sub-router. Cloneable (all `Arc`) so axum can share it. +#[derive(Clone)] +pub(crate) struct MandateApiState { + /// The SAME standing-grant registry the API server issues mandates into. + pub(crate) standing_service: Arc, + /// Owns the durable audit chain (receipt export) and the token-revocation liveness check. + pub(crate) capability_manager: Arc, + /// Home-launch-token trust root (the operator's 0600 files under the data dir). + pub(crate) data_dir: PathBuf, + /// The SAME meter+ledger the executor's pay gate enforces with (Sprint 31) — the Money + /// panel's read/provision/reconcile surface. `None` ⇒ pay unwired ⇒ those routes answer 503. + pub(crate) pay_rail: Option, + /// Sprint 33: fresh passkey tokens already SPENT on a money write, keyed by token digest with + /// a prune-by deadline. One fresh verification authorizes exactly ONE money write on this + /// surface — a second write with the same token is a replay and is refused. In-memory and + /// bounded (entries outlive the freshness window by only a skew margin; see + /// [`consume_fresh_money_token`]). RESIDUAL (documented in KNOWN_GAPS G-M9): a gateway + /// restart clears it, so a token younger than the freshness window could be replayed once + /// across a restart — the window is [`MONEY_FRESH_WINDOW_SECS`]. + pub(crate) spent_fresh_money_tokens: + Arc>>, + /// Sprint 38: the Marketplace panel's per-asset quote cache (TTL-bounded; see + /// [`MARKET_QUOTE_TTL_SECS`]) — a browser refresh storm costs at most one chain read per + /// asset per window. + pub(crate) marketplace_quote_cache: MarketQuoteCache, +} + +/// The mandates capsule id — must match `capsules/mandates/capsule.json`'s `name`. +pub(crate) const MANDATES_CAPSULE_ID: &str = "mandates"; + +/// Anti-CSRF marker for COOKIE-authorized writes (Sprint 33). A cookie is an ambient credential +/// — the browser attaches it to any same-site request regardless of who initiated it — so a +/// write authorized by the cookie must ALSO carry this custom header: setting a custom header +/// cross-origin forces a CORS preflight the gateway never grants to a foreign origin (no ACAO +/// on these routes — see the S31 F2 regression +/// test). Header-token writes don't need it — the token header itself is the unforgeable marker. +pub(crate) const MANDATES_APP_MARKER_HEADER: &str = "x-elastos-mandates-app"; + +/// How fresh the money-write passkey verification must be, in seconds — the same window the +/// wallet's send path uses (one shared operator expectation: "verify, then act, within ~3 +/// minutes"). +const MONEY_FRESH_WINDOW_SECS: u64 = 180; + +/// Hard cap on the spent-token guard map (defense in depth; each entry requires a REAL passkey +/// ceremony to create, so an honest operator never approaches it). When full after pruning, money +/// writes are REFUSED — fail closed, never fail open by dropping replay protection. +const MONEY_SPENT_GUARD_MAX: usize = 4096; + +/// The WEB surface's spend-cap ceiling (council S31 G-F1/RT-F5): the shell app can provision caps +/// up to this many units; anything larger is a deliberate CLI/consent-broker act. Server-side — +/// an XSS in the frame holding the in-URL token cannot provision an unbounded cap. Overridable +/// per deployment via `ELASTOS_WEB_MAX_SPEND_CAP` (the unit is the deployment's spend unit). +const WEB_MAX_SPEND_CAP_DEFAULT: u64 = 1_000_000; + +fn web_max_spend_cap() -> u64 { + match std::env::var("ELASTOS_WEB_MAX_SPEND_CAP") { + Ok(raw) => match raw.trim().parse::() { + Ok(cap) => cap, + // A typo'd override on a money ceiling must not fall back in silence. + Err(e) => { + tracing::warn!( + "ELASTOS_WEB_MAX_SPEND_CAP {raw:?} is not a u64 ({e}) — using the default \ + ceiling {WEB_MAX_SPEND_CAP_DEFAULT}" + ); + WEB_MAX_SPEND_CAP_DEFAULT + } + }, + Err(_) => WEB_MAX_SPEND_CAP_DEFAULT, + } +} + +/// The one launch-token gate every mandates route runs (Sprint 33): accepts the token from the +/// `x-elastos-home-token` header (tests, tools, pre-S33 clients) OR from the HttpOnly +/// path-scoped [`MANDATES_SESSION_COOKIE`] the shell launch response set. For WRITES authorized +/// by the COOKIE, the request must also carry [`MANDATES_APP_MARKER_HEADER`] — a cookie is +/// ambient browser state, and the custom header is what proves a same-origin script (not a +/// cross-site form) built the request. Returns the token's authority context for the money +/// routes' fresh-passkey check. +fn require_mandates_surface( + state: &MandateApiState, + headers: &HeaderMap, + write: bool, +) -> Result> { + let (context, transport) = super::require_home_launch_token_context_transport( + &state.data_dir, + headers, + MANDATES_CAPSULE_ID, + MANDATES_SESSION_COOKIE, + ) + .map_err(|err| Box::new(mandate_auth_error(err)))?; + if write + && transport == super::gateway_home_token::HomeTokenTransport::Cookie + && !headers.contains_key(MANDATES_APP_MARKER_HEADER) + { + return Err(Box::new( + ( + StatusCode::FORBIDDEN, + format!( + "cookie-authorized writes must carry the {MANDATES_APP_MARKER_HEADER} header \ + (cross-site request refused)" + ), + ) + .into_response(), + )); + } + Ok(context) +} + +/// The money-write authority gate (Sprint 33, council S31 F1): on top of the launch-token gate, +/// a money WRITE requires a FRESH passkey verification — a proof-bound Home token minted by a +/// WebAuthn ceremony at most [`MONEY_FRESH_WINDOW_SECS`] ago for the SAME principal the standing +/// token names — and each such verification is SPENT on first use (one ceremony = one write; +/// replaying the token on any money verb, same or different, is refused). What this proves is +/// exactly and only: THIS operator's authenticator freshly approved ONE state-changing money +/// operation. It does not scope WHICH write at mint time — single-use consumption is the +/// mechanism that keeps one assertion from authorizing a second write. +/// +/// The standing 12h launch token alone can no longer move money: before this sprint the exact +/// failure was that a leaked launch URL (or a ridden session) could provision budgets and force +/// reconciliations for 12 hours. +fn require_fresh_money_authorization( + state: &MandateApiState, + headers: &HeaderMap, + fresh_passkey_token: &str, +) -> Result> { + let context = require_mandates_surface(state, headers, true)?; + let canonical_assertion = super::require_fresh_passkey_home_token( + &state.data_dir, + fresh_passkey_token, + &context, + MONEY_FRESH_WINDOW_SECS, + ) + .map_err(|err| { + Box::new( + ( + StatusCode::UNAUTHORIZED, + format!( + "money writes require a fresh passkey verification (at most \ + {MONEY_FRESH_WINDOW_SECS}s old): {err}" + ), + ) + .into_response(), + ) + })?; + consume_fresh_money_token(state, &canonical_assertion) +} + +/// A CONSUMED fresh verification: proof the single-use guard admitted this write, carrying the +/// canonical key so the handler can RE-CREDIT it if the write is refused provably before any +/// money effect (council S33 red-team F1 — see [`SpentFreshVerification::refund`]). +struct SpentFreshVerification { + key: String, +} + +impl SpentFreshVerification { + /// Re-credit the verification: the write it admitted was refused PROVABLY BEFORE any money + /// effect — the surface's own guards (rail unwired, cap ceiling) or the shared cores' 4xx + /// rejections (validation / unknown key / already-resolved, all pre-effect by the cores' + /// construction) — so the operator's ceremony is not burned on a no-op. Same contract as + /// the carrier's `DidNotAct` refunds (BUG-4): refund ONLY when a replay is a guaranteed + /// no-op because nothing acted; any 5xx from the cores stays SPENT — it may have acted + /// (indeterminate keeps the consumption, exactly like the pay path keeps its reservation). + fn refund(self, state: &MandateApiState) { + let mut spent = state + .spent_fresh_money_tokens + .lock() + .unwrap_or_else(|poisoned| poisoned.into_inner()); + spent.remove(&self.key); + } +} + +/// Spend the fresh verification: exactly ONE money write per WebAuthn ceremony. Keyed by the +/// SHA-256 of the CANONICAL payload the signature was verified over — NEVER the raw token +/// string (council S33 guardian F1): the same assertion can be re-encoded into byte-different +/// token strings that all still verify, so a raw-string key would see each re-encoding as +/// unspent; the canonical form collapses every valid re-encoding onto one key, and altering any +/// field to mint a new key breaks the signature. Each real ceremony mints unique grant/session +/// ids, so distinct ceremonies never collide. Entries are pruned once they out-age the +/// freshness window (plus the same 60s issue-skew the verifier tolerates), so the map stays +/// bounded by the number of REAL ceremonies inside a ~4-minute window; if it is somehow full, +/// we refuse — fail closed, never drop replay protection to accept a write. +fn consume_fresh_money_token( + state: &MandateApiState, + canonical_assertion: &str, +) -> Result> { + use sha2::Digest as _; + let key = hex::encode(sha2::Sha256::digest(canonical_assertion.as_bytes())); + let now = now_ts(); + let mut spent = state + .spent_fresh_money_tokens + .lock() + .unwrap_or_else(|poisoned| poisoned.into_inner()); + spent.retain(|_, prune_at| *prune_at > now); + if spent.contains_key(&key) { + return Err(Box::new( + ( + StatusCode::FORBIDDEN, + "this passkey verification was already spent on a money write — each money \ + write needs its own fresh verification" + .to_string(), + ) + .into_response(), + )); + } + if spent.len() >= MONEY_SPENT_GUARD_MAX { + return Err(Box::new( + ( + StatusCode::SERVICE_UNAVAILABLE, + "money-write replay guard is at capacity; retry shortly".to_string(), + ) + .into_response(), + )); + } + spent.insert(key.clone(), now + MONEY_FRESH_WINDOW_SECS + 60); + Ok(SpentFreshVerification { key }) +} + +/// A money WRITE body: the shared input plus the fresh passkey verification that authorizes this +/// one write. The inner shape is byte-identical to the consent-broker API's — the fresh token is +/// this WEB surface's own requirement (same narrowing discipline as the cap ceiling), so it +/// wraps rather than forks the shared struct. +#[derive(Debug, serde::Deserialize)] +struct FreshMoneyWrite { + /// A proof-bound Home token from `/api/auth/passkey/authenticate/complete`, at most + /// [`MONEY_FRESH_WINDOW_SECS`] old, spent by this call. + fresh_passkey_token: String, + input: T, +} + +/// GET /api/apps/mandates/standing-grants — the shell app's live mandate list. +/// +/// Delegates to [`crate::api::handlers::capability::mandate_cards`] — the ONE shared projection the +/// API server also serves — so the liveness invariant (a revoked/expired/epoch-killed mandate never +/// renders "Live") can never drift between the two surfaces. +async fn mandates_list( + State(state): State, + headers: HeaderMap, +) -> axum::response::Response { + if let Err(resp) = require_mandates_surface(&state, &headers, false) { + return *resp; + } + Json( + crate::api::handlers::capability::mandate_cards( + &state.standing_service, + &state.capability_manager, + ) + .await, + ) + .into_response() +} + +/// GET /api/apps/mandates/agent-state — the operator's view of durable agent state (Sprint 18). +/// +/// Read-only, OPERATOR-scoped: it spans every principal because the caller is the shell (the +/// runtime's grant root, gated by the same home-launch token as the mandate list), the trust level +/// that already sees every mandate. It is NOT an agent path — agents remain isolated by the +/// per-principal `get_agent_state`; this only lets the OWNER watch what its agents have written +/// under their mandates. The value shown is the `input_hash` COMMITMENT (labelled as such by the +/// UI), never content bytes — the store holds no payload. +async fn agent_state_list( + State(state): State, + headers: HeaderMap, +) -> axum::response::Response { + if let Err(resp) = require_mandates_surface(&state, &headers, false) { + return *resp; + } + match crate::agent_store::list_agent_state(&state.data_dir) { + Ok(entries) => Json(serde_json::json!({ "entries": entries })).into_response(), + Err(e) => ( + StatusCode::INTERNAL_SERVER_ERROR, + format!("could not read agent state: {e}"), + ) + .into_response(), + } +} + +/// GET /api/apps/mandates/mandate/:token_id/receipt — the portable per-mandate receipt. +/// +/// Mirrors [`crate::api::handlers::capability::mandate_receipt`]: read-only over the durable chain; +/// `404` when the token has no durable records (absence reported, never fabricated). +async fn mandate_receipt( + State(state): State, + Path(token_id): Path, + headers: HeaderMap, +) -> axum::response::Response { + if let Err(resp) = require_mandates_surface(&state, &headers, false) { + return *resp; + } + let token_id = match TokenId::from_hex(token_id.trim()) { + Ok(id) => id.to_string(), + Err(e) => { + return (StatusCode::BAD_REQUEST, format!("invalid token id: {e}")).into_response() + } + }; + match state + .capability_manager + .audit_log() + .export_mandate_receipt_for_capability(&token_id) + { + Some(receipt) => Json(receipt).into_response(), + None => ( + StatusCode::NOT_FOUND, + format!("no durable audit records for mandate {token_id}"), + ) + .into_response(), + } +} + +#[derive(Debug, serde::Deserialize)] +#[serde(deny_unknown_fields)] +struct RevokeBody { + /// The mandate's token id (the same id the card carries). + grant_id: String, +} + +/// POST /api/apps/mandates/standing-grants/revoke — the operator's kill switch, from the shell. +/// +/// Delegates to [`crate::api::handlers::capability::revoke_mandate`] — the SAME fail-closed kill +/// path the API server uses (signed `CapabilityRevoke` durably attested BEFORE the envelope dies; +/// an unattestable revoke ABORTS loudly). Returns `{revoked: bool}`: `true` iff a live envelope was +/// killed by THIS call (idempotent — an already-dead or unknown mandate reads `false`, honestly). +/// This is the surface's only mutation, and it exclusively REMOVES authority. +async fn mandate_revoke( + State(state): State, + headers: HeaderMap, + Json(body): Json, +) -> axum::response::Response { + if let Err(resp) = require_mandates_surface(&state, &headers, true) { + return *resp; + } + match crate::api::handlers::capability::revoke_mandate( + &state.standing_service, + &state.capability_manager, + &body.grant_id, + "standing grant revoked via shell mandates app", + ) + .await + { + Ok(revoked) => Json(serde_json::json!({ "revoked": revoked })).into_response(), + Err((status, msg)) => (status, msg).into_response(), + } +} + +/// POST /api/apps/mandates/standing-grants/issue — grant a mandate from the shell app. +/// +/// Delegates to [`crate::api::handlers::capability::issue_mandate`] — the SAME fail-closed mint +/// path the API server uses (action whitelist, non-empty methods, AUD-5 overbroad-wildcard +/// refusal, agent-key validation, durable-before-visible issuance) — so the guards cannot drift. +/// Authority-granting, therefore shell-only twice over: the home-token gate here AND the launch +/// token itself only exists because the shell (the runtime's grant root, G-M3) opened the app. +async fn mandate_issue( + State(state): State, + headers: HeaderMap, + Json(body): Json, +) -> axum::response::Response { + if let Err(resp) = require_mandates_surface(&state, &headers, true) { + return *resp; + } + // Least privilege (Sprint 15 council, P16): the web mint surface is DELIBERATELY narrower than + // the raw API — `admin` mandates are minted from the CLI/consent-broker API only, never from + // this iframe. Enforced server-side (not just hidden in the form) so an XSS in the frame that + // POSTs `action:"admin"` with the in-URL token is still refused. The shared helper keeps admin + // for the API/CLI path; this narrowing is the gateway surface's own. + if body.action.trim().eq_ignore_ascii_case("admin") { + return ( + StatusCode::FORBIDDEN, + "admin mandates are minted from the CLI, not the shell app".to_string(), + ) + .into_response(); + } + // G-M4 default-bound (Sprint 20): the web mint surface REQUIRES an agent key — an unbound + // (capsule-string-only) mandate lets ANY key acting as the capsule act, weak attribution that + // should be a deliberate operator choice, not a one-click default. Enforced server-side (not + // just prompted in the form) so the narrower posture holds even against an XSS in the frame. + // Unbound mandates remain available on the CLI/consent-broker API for the trusted operator + // (G-M3) — this narrowing, like the admin refusal above, is the gateway surface's own. + if body + .agent_pubkey + .as_deref() + .map(str::trim) + .filter(|k| !k.is_empty()) + .is_none() + { + return ( + StatusCode::BAD_REQUEST, + "a mandate granted from the shell must bind an agent key (unbound mandates are \ + CLI-only); paste the agent's 64-hex ed25519 public key" + .to_string(), + ) + .into_response(); + } + // Sprint 32 narrowing (same discipline as the agent-key requirement above): a mandate granted + // from the shell must NAME its responsible entity — the operator is right there, and the + // liability binding is the point of the web mint. Server-side, so an XSS in the frame cannot + // mint an accountability-less mandate. Unrecorded-entity mints remain a deliberate CLI act. + if body + .responsible_entity + .as_deref() + .map(str::trim) + .filter(|d| !d.is_empty()) + .is_none() + { + return ( + StatusCode::BAD_REQUEST, + "a mandate granted from the shell must name its responsible entity — the operator/legal \ + entity DID accountable for the agent's acts (e.g. did:web:acme.example); \ + entity-less mandates are CLI-only" + .to_string(), + ) + .into_response(); + } + match crate::api::handlers::capability::issue_mandate( + &state.standing_service, + &state.capability_manager, + body, + ) + .await + { + Ok(out) => Json(out).into_response(), + Err((status, msg)) => (status, msg).into_response(), + } +} + +/// GET /api/apps/mandates/money — the Money panel's one-call read (Sprint 31): every provisioned +/// budget (with held-unconfirmed `pending_units` distinct from confirmed spend), the +/// reconciliation work list, and the poisoned flag. OPERATOR-scoped like the agent-state view: it +/// spans every capsule because the caller is the shell (the runtime's grant root, gated by the +/// same home-launch token), the trust level that already sees — and can raise — every cap — a READ-ONLY projection of the same meter and +/// ledger the pay gate enforces with (delegating to the shared +/// [`money_overview`](crate::api::handlers::capability::money_overview), so the two surfaces can +/// never drift). 503 when pay is unwired — absence reported, never an empty fabrication. +async fn money_view( + State(state): State, + headers: HeaderMap, +) -> axum::response::Response { + if let Err(resp) = require_mandates_surface(&state, &headers, false) { + return *resp; + } + let Some(rail) = &state.pay_rail else { + return ( + StatusCode::SERVICE_UNAVAILABLE, + "no payment rail is wired".to_string(), + ) + .into_response(); + }; + Json(crate::api::handlers::capability::money_overview( + &rail.meter, + &rail.ledger, + )) + .into_response() +} + +/// POST /api/apps/mandates/spend-budget — provision (or re-set) a capsule's money cap from the +/// shell app. Authority-granting like `issue` (home-launch token = the shell grant root, G-M3) +/// AND, as a MONEY write (Sprint 33), requiring a fresh single-use passkey verification in the +/// body (`fresh_passkey_token` — see [`require_fresh_money_authorization`]). Delegates to the +/// ONE shared provisioning path +/// ([`set_spend_budget_core`](crate::api::handlers::capability::set_spend_budget_core)) so every +/// fail-closed guard (durable-only, slug bound, apply-then-attest with true rollback, loud double +/// failure) holds identically on both surfaces. +async fn money_set_budget( + State(state): State, + headers: HeaderMap, + Json(body): Json>, +) -> axum::response::Response { + let spent = match require_fresh_money_authorization(&state, &headers, &body.fresh_passkey_token) + { + Ok(spent) => spent, + Err(resp) => return *resp, + }; + let body = body.input; + let Some(rail) = &state.pay_rail else { + // Pre-effect refusal: nothing is wired, nothing acted — the ceremony is re-credited. + spent.refund(&state); + return ( + StatusCode::SERVICE_UNAVAILABLE, + "no payment rail is wired — a spend budget nothing enforces is refused".to_string(), + ) + .into_response(); + }; + // The web surface's own narrowing (module doc; mirrors the issue route's admin refusal): + // enforced HERE, server-side, so an XSS in the frame is still ceiling-bound. The raw + // consent-broker API carries no ceiling — a larger cap is a deliberate operator act. + let ceiling = web_max_spend_cap(); + if body.limit > ceiling { + // Pre-effect refusal: the core never ran — the ceremony is re-credited. + spent.refund(&state); + return ( + StatusCode::FORBIDDEN, + format!( + "caps above {ceiling} units are set from the CLI/consent-broker API, not the \ + shell app (ELASTOS_WEB_MAX_SPEND_CAP raises this surface's ceiling)" + ), + ) + .into_response(); + } + match crate::api::handlers::capability::set_spend_budget_core( + &rail.meter, + Some(&rail.ledger), + state.capability_manager.audit_log(), + body, + ) { + Ok(out) => Json(out).into_response(), + Err((status, msg)) => { + // A 4xx from the shared core is a pre-effect rejection by construction (validation, + // slug bound) — re-credit. A 5xx may have partially acted (apply-then-attest) — the + // ceremony stays spent, mirroring the pay path's indeterminate-keeps-reservation. + if status.is_client_error() { + spent.refund(&state); + } + (status, msg).into_response() + } + } +} + +/// POST /api/apps/mandates/payments/reconcile — resolve ONE indeterminate payment against the +/// rail's verdict, from the shell app. A MONEY write (Sprint 33): requires its own fresh +/// single-use passkey verification in the body (`fresh_passkey_token`), like `spend-budget` — +/// one ceremony authorizes one write. Delegates to the ONE shared reconciliation path +/// ([`reconcile_payment_core`](crate::api::handlers::capability::reconcile_payment_core)): +/// exactly-once resolve, refund only on durable Ok, structured 404/409/503, chain attestation — +/// identical on both surfaces by construction. +async fn money_reconcile( + State(state): State, + headers: HeaderMap, + Json(body): Json>, +) -> axum::response::Response { + let spent = match require_fresh_money_authorization(&state, &headers, &body.fresh_passkey_token) + { + Ok(spent) => spent, + Err(resp) => return *resp, + }; + let body = body.input; + let Some(rail) = &state.pay_rail else { + // Pre-effect refusal: nothing is wired, nothing acted — the ceremony is re-credited. + spent.refund(&state); + return ( + StatusCode::SERVICE_UNAVAILABLE, + "no payment rail is wired".to_string(), + ) + .into_response(); + }; + match crate::api::handlers::capability::reconcile_payment_core( + &rail.ledger, + &rail.meter, + state.capability_manager.audit_log(), + body, + ) { + Ok(out) => Json(out).into_response(), + Err((status, msg)) => { + // 404 (unknown key) / 409 (already resolved) are pre-effect lookups by the core's + // construction — re-credit. A 5xx may be indeterminate — the ceremony stays spent. + if status.is_client_error() { + spent.refund(&state); + } + (status, msg).into_response() + } + } +} + +// ─────────────────────────── The Marketplace panel (Sprint 38) ─────────────────────────── +// +// STRICTLY READ-ONLY: every pixel is a projection of the one enforcing registry + meter + ledger +// (same Arcs as the pay gate, by construction). The panel never gains a "buy" verb — operators +// GRANT (the issue route), agents ACT (the signed-intent dispatch routes on the API server); +// this surface only shows what the mandates scope and what the ledger says happened. + +pub(crate) use crate::market_quote::{ + claim_or_serve, quote_outcome, CachedQuote, MarketQuote, MarketQuoteCache, + MARKET_QUOTE_TTL_SECS, +}; + +/// At most this many FRESH chain reads per view. Cache hits are free (they cost no chain read and +/// never consume a slot), so with the TTL this rotates quote coverage across refreshes instead of +/// permanently starving the alphabetically-last assets: view 1 reads assets 1-8, view 2 finds +/// them cached and reads 9-16, and so on. +const MARKET_MAX_QUOTED_ASSETS: usize = 8; +/// How many SETTLED (terminal) ledger entries the buys table projects. Pending buys are NEVER +/// truncated — an operator watch surface must not let a flood of new terminals push a live +/// obligation out of sight. +const MARKET_BUYS_LIMIT: usize = 64; + +#[derive(serde::Serialize)] +struct MarketAssetView { + /// The DRM asset reference (the pay resource's payee suffix — the KID / content id). + asset: String, + /// Token ids of the ACTIVE pay-mandates scoped to this asset. + mandates: Vec, + /// The live on-chain terms (cached up to [`MARKET_QUOTE_TTL_SECS`]); absent iff unquoted. + #[serde(skip_serializing_if = "Option::is_none")] + quote: Option, + /// True when this asset had no cached quote AND this view's fresh-read slots were already + /// taken — stated, not silently dropped; the TTL rotation reaches it on a later refresh. + #[serde(skip_serializing_if = "std::ops::Not::not")] + unquoted_over_cap: bool, +} + +#[derive(serde::Serialize)] +struct MarketBuyView { + /// The payee — the DRM asset reference the buy targeted. + asset: String, + /// The acting capsule (agent identity). + capsule: String, + /// Spend units authorized by the signed intent. + amount: u64, + /// Machine state: refused | pending | charged | confirmed | refunded. + state: String, + /// The honest operator wording for `state` (a broadcast is NEVER "purchased"). + detail: String, + /// The broadcast tx hash, when the rail reference carries one (`drm:tx=…`). + #[serde(skip_serializing_if = "Option::is_none")] + tx: Option, + /// The mandate the buy acted under, when recorded. + #[serde(skip_serializing_if = "Option::is_none")] + mandate: Option, +} + +#[derive(serde::Serialize)] +struct MarketplaceView { + /// The rights mode the quotes were read under — "chain" is live truth; "dev"/"chainmock" + /// quote FREE (price 0), and the panel must say so rather than display a fake price. + rights_mode: String, + assets: Vec, + buys: Vec, + /// How many entries the ledger holds in total — when it exceeds `buys.len()`, the table is + /// honestly a WINDOW (pending always included; only the terminal tail is capped). + buys_total: usize, + buys_limit: usize, + quote_ttl_secs: u64, +} + +/// Map one ledger record to its honest display row. The wording rule (P12): a broadcast-accepted +/// buy reads "awaiting chain confirmation" — `confirmed` is reserved for the chain's own verdict +/// (or the operator's explicit reconcile), never the broadcast. +fn market_buy_view(record: &crate::payment_ledger::PaymentRecord) -> MarketBuyView { + use crate::payment_ledger::PaymentStatus; + // Display-bounded: the rail note is rail-controlled bytes — a real tx hash is 66 chars, so + // an over-long "tx" is garbage that must not bloat the payload/DOM. + let tx = crate::drm_marketplace::parse_drm_tx(&record.rail_note) + .map(|t| t.chars().take(80).collect::()); + let (state, detail) = match record.status { + PaymentStatus::Pending => ( + "pending", + if tx.is_some() { + "broadcast — awaiting chain confirmation" + } else { + "indeterminate — awaiting reconciliation" + }, + ), + PaymentStatus::Performed => ("charged", "charged (rail-attested)"), + PaymentStatus::ResolvedCharged => ( + "confirmed", + if tx.is_some() { + "confirmed on-chain" + } else { + "confirmed (reconciled against the rail)" + }, + ), + PaymentStatus::NotCharged => ("refused", "refused — nothing charged"), + PaymentStatus::ResolvedNotCharged => ("refunded", "refunded — the reservation came back"), + }; + MarketBuyView { + asset: record.payee.clone(), + capsule: record.capsule.clone(), + amount: record.amount, + state: state.to_string(), + detail: detail.to_string(), + tx, + mandate: record.token_id.clone(), + } +} + +/// GET /api/apps/mandates/marketplace — the Marketplace panel's one read: the assets the ACTIVE +/// pay-mandates scope (with live, cached, fan-out-bounded quotes) and the recent buys as the +/// ledger records them. 503 without a wired rail (a marketplace with no money path is not a +/// marketplace — same posture as the Money panel). +async fn marketplace_view( + State(state): State, + headers: HeaderMap, +) -> axum::response::Response { + if let Err(resp) = require_mandates_surface(&state, &headers, false) { + return *resp; + } + let Some(rail) = &state.pay_rail else { + return ( + StatusCode::SERVICE_UNAVAILABLE, + "no payment rail is wired".to_string(), + ) + .into_response(); + }; + + // 1. The assets: every ACTIVE mandate whose envelope authorizes runtime.pay on a pay + // resource, grouped by asset (deterministic order — BTreeMap). + let cards = crate::api::handlers::capability::mandate_cards( + &state.standing_service, + &state.capability_manager, + ) + .await; + let mut by_asset: std::collections::BTreeMap> = Default::default(); + for card in &cards.mandates { + if !card.active || !card.methods.iter().any(|m| m == "runtime.pay") { + continue; + } + let Some(asset) = card + .resource + .strip_prefix(crate::intent_executor::PAY_PREFIX) + else { + continue; + }; + if asset.is_empty() { + continue; + } + by_asset + .entry(asset.to_string()) + .or_default() + .push(card.token_id.clone()); + } + + // 2. The quotes. ONE claim pass under the cache lock decides everything (single-flight, + // council S38 fold): a fresh cached quote is served free (a cache hit never consumes a + // fresh-read slot); a fresh IN-FLIGHT sentinel means another view is already reading — + // serve "in progress", never a duplicate read; a miss CLAIMS the slot (sentinel inserted + // under the lock, before any read starts) up to MARKET_MAX_QUOTED_ASSETS fresh reads per + // view. So "at most one live chain read per asset per TTL window" is literal under any + // concurrency, and coverage ROTATES across refreshes instead of starving the tail. + let now = now_ts(); + crate::market_quote::prune(&state.marketplace_quote_cache, now); // once per view + let mut assets = Vec::with_capacity(by_asset.len()); + let mut to_quote: Vec = Vec::new(); + for (asset, mandates) in by_asset { + // The SHARED single-flight claim pass (crate::market_quote — the same spine the + // runtime.market_quote affordance uses): serve fresh free, respect an in-flight claim, + // claim up to this view's fresh-read budget, and state the over-budget tail. + let may_claim = to_quote.len() < MARKET_MAX_QUOTED_ASSETS; + let (quote, over_cap) = + match claim_or_serve(&state.marketplace_quote_cache, &asset, now, may_claim) { + CachedQuote::Fresh(q) => (Some(q), false), + CachedQuote::InFlight => (None, false), + CachedQuote::Claimed => { + to_quote.push(asset.clone()); + (None, false) + } + CachedQuote::NotClaimed => (None, true), + }; + assets.push(MarketAssetView { + asset, + mandates, + quote, + unquoted_over_cap: over_cap, + }); + } + if !to_quote.is_empty() { + let fresh = tokio::task::spawn_blocking(move || { + to_quote + .into_iter() + .map(|asset| { + let quote = quote_outcome(crate::api::buy_authority::quote_buy( + &asset, + &crate::api::buy_authority::BuyTarget::default(), + )); + (asset, quote) + }) + .collect::>() + }) + .await + .unwrap_or_default(); + for (asset, quote) in fresh { + // Stamped AFTER the read returned (council S38 red-team F4): a slow fetch must not + // be served as "fresh" for a full TTL past its actual read time. + crate::market_quote::fill( + &state.marketplace_quote_cache, + &asset, + quote.clone(), + now_ts(), + ); + if let Some(view) = assets.iter_mut().find(|a| a.asset == asset) { + view.quote = Some(quote); + } + } + } + + // 3. The buys: every PENDING entry (a live obligation is never pushed out of sight by a + // flood of newer terminals — council S38 fold) plus the most recent settled tail, newest + // first, with the window stated via buys_total/buys_limit. + let ledger = &rail.ledger; + let buys_total = ledger.len(); + let mut records = ledger.pending(); + for r in ledger.recent(MARKET_BUYS_LIMIT) { + if r.status != crate::payment_ledger::PaymentStatus::Pending { + records.push(r); + } + } + records.sort_by_key(|r| std::cmp::Reverse(r.seq)); + let buys: Vec = records.iter().map(market_buy_view).collect(); + + Json(MarketplaceView { + rights_mode: format!("{:?}", crate::api::rights_authority::rights_mode()).to_lowercase(), + assets, + buys, + buys_total, + buys_limit: MARKET_BUYS_LIMIT, + quote_ttl_secs: MARKET_QUOTE_TTL_SECS, + }) + .into_response() +} + +/// A failed home-token gate reads as `401` — the app was not launched through the shell. +fn mandate_auth_error(err: anyhow::Error) -> axum::response::Response { + (StatusCode::UNAUTHORIZED, err.to_string()).into_response() +} + +/// Build the mandates sub-router (read + the revoke kill switch), erased over its own state so the +/// gateway can `.merge()` it without disturbing `GatewayState`. +pub(crate) fn mandate_router(state: MandateApiState) -> Router { + Router::new() + .route("/api/apps/mandates/standing-grants", get(mandates_list)) + .route("/api/apps/mandates/agent-state", get(agent_state_list)) + .route( + "/api/apps/mandates/mandate/:token_id/receipt", + get(mandate_receipt), + ) + .route( + "/api/apps/mandates/standing-grants/revoke", + post(mandate_revoke), + ) + .route( + "/api/apps/mandates/standing-grants/issue", + post(mandate_issue), + ) + // The Money panel (Sprint 31): read the budgets+work-list projection, provision a cap, + // resolve an indeterminate payment — all over the same home-launch-token gate. + .route("/api/apps/mandates/money", get(money_view)) + .route("/api/apps/mandates/spend-budget", post(money_set_budget)) + .route( + "/api/apps/mandates/payments/reconcile", + post(money_reconcile), + ) + // The Marketplace panel (Sprint 38): strictly read-only — assets scoped by pay-mandates + // with live (cached, fan-out-bounded) quotes, and the buys as the ledger records them. + .route("/api/apps/mandates/marketplace", get(marketplace_view)) + .with_state(state) +} + +#[cfg(test)] +mod tests { + use super::*; + use axum::body::Body; + use axum::http::Request; + use elastos_runtime::capability::token::TokenConstraints; + use elastos_runtime::capability::{Action, CapabilityStore, ResourceId, StandingGrantService}; + use elastos_runtime::primitives::audit::AuditLog; + use elastos_runtime::primitives::metrics::MetricsManager; + use tower::ServiceExt; + + const HOME_TOKEN_HEADER: &str = "x-elastos-home-token"; + + /// A fresh manager + the standing service backed by it (the SAME registry, as in serve). + fn manager_and_service() -> (Arc, Arc) { + let audit_log = Arc::new(AuditLog::new()); + let store = Arc::new(CapabilityStore::new()); + let metrics = Arc::new(MetricsManager::new()); + let capability_manager = Arc::new(CapabilityManager::new(store, audit_log, metrics)); + let standing_service = Arc::new(capability_manager.standing_grant_service()); + (capability_manager, standing_service) + } + + fn state_for(dir: &std::path::Path) -> MandateApiState { + let (capability_manager, standing_service) = manager_and_service(); + MandateApiState { + standing_service, + capability_manager, + data_dir: dir.to_path_buf(), + pay_rail: None, + spent_fresh_money_tokens: Arc::default(), + marketplace_quote_cache: Arc::default(), + } + } + + /// Sprint 33 fixture: a standing mandates launch token plus `fresh` DISTINCT fresh-passkey + /// Home tokens for the SAME principal. Each fresh token is backed by its own active + /// proof-bound session grant with unique session/grant ids — exactly what each real WebAuthn + /// ceremony mints in production (so no two fixtures collapse to the same token string). + fn money_write_tokens(dir: &std::path::Path, fresh: usize) -> (String, Vec) { + let principal = "person:local:money-op".to_string(); + let standing_ctx = HomeLaunchTokenContext { + principal_id: principal.clone(), + session_id: "local:standing".to_string(), + proof_binding_id: None, + grant_id: "grant:standing".to_string(), + }; + let standing = super::super::issue_home_launch_token_with_context( + dir, + MANDATES_CAPSULE_ID, + &standing_ctx, + ) + .unwrap(); + let now = now_ts(); + let mut tokens = Vec::new(); + for i in 0..fresh { + let ctx = HomeLaunchTokenContext { + principal_id: principal.clone(), + session_id: format!("auth:fresh-{i}"), + proof_binding_id: Some(format!("proof:passkey:money-{i}")), + grant_id: format!("grant:fresh-{i}"), + }; + crate::auth::store_session_grant( + dir, + elastos_runtime::auth::AuthSessionGrantV1 { + schema: elastos_runtime::auth::AuthSessionGrantV1::SCHEMA.to_string(), + grant_id: ctx.grant_id.clone(), + session_id: ctx.session_id.clone(), + principal_id: ctx.principal_id.clone(), + proof_binding_id: ctx.proof_binding_id.clone().unwrap(), + issued_at: now, + expires_at: now + 3600, + apps: vec![HOME_CAPSULE_ID.to_string()], + }, + ) + .unwrap(); + tokens.push( + super::super::issue_home_launch_token_with_context(dir, HOME_CAPSULE_ID, &ctx) + .unwrap(), + ); + } + (standing, tokens) + } + + /// A money-write body in the Sprint 33 shape: the shared input wrapped with the fresh + /// verification that authorizes this one write. + fn money_body(fresh_token: &str, input: &str) -> String { + format!( + r#"{{"fresh_passkey_token":{},"input":{input}}}"#, + serde_json::json!(fresh_token) + ) + } + + /// Helper: POST a JSON body to a route with optional home token, return the response. + async fn post_json( + app: Router, + uri: &str, + token: Option, + body: &str, + ) -> axum::http::Response { + let mut req = Request::builder() + .method("POST") + .uri(uri) + .header("content-type", "application/json"); + if let Some(t) = token { + req = req.header(HOME_TOKEN_HEADER, t); + } + app.oneshot(req.body(Body::from(body.to_string())).unwrap()) + .await + .unwrap() + } + + /// The MINT is gated like everything else: no home-launch token ⇒ 401 AND nothing is minted — + /// an unauthenticated caller can never grant an agent authority. + #[tokio::test] + async fn issue_route_requires_home_launch_token_and_mints_nothing() { + let dir = tempfile::tempdir().unwrap(); + let state = state_for(dir.path()); + let app = mandate_router(state.clone()); + let resp = post_json( + app, + "/api/apps/mandates/standing-grants/issue", + None, + r#"{"capsule":"vm-agent","resource":"elastos://mail/send","action":"execute","methods":["send"],"ttl_secs":3600}"#, + ) + .await; + assert_eq!(resp.status(), StatusCode::UNAUTHORIZED); + assert!( + state.standing_service.list().is_empty(), + "an unauthenticated issue must mint NOTHING" + ); + } + + /// Grant from the shell: a valid issue over the route mints a LIVE mandate in the SHARED + /// registry, visible on the list surface, with the returned grant id. + #[tokio::test] + async fn issue_route_mints_a_live_mandate_in_the_shared_registry() { + let dir = tempfile::tempdir().unwrap(); + let state = state_for(dir.path()); + let token_hdr = + super::super::issue_home_launch_token(dir.path(), MANDATES_CAPSULE_ID).unwrap(); + // The web surface grants BOUND mandates (G-M4) — pass a REAL, non-weak agent key. + let agent = hex::encode( + ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()) + .verifying_key() + .to_bytes(), + ); + let resp = post_json( + mandate_router(state.clone()), + "/api/apps/mandates/standing-grants/issue", + Some(token_hdr), + &format!( + r#"{{"capsule":"vm-agent","resource":"elastos://mail/send","action":"execute","methods":["send"],"ttl_secs":3600,"agent_pubkey":"{agent}","responsible_entity":"did:web:acme.example"}}"# + ), + ) + .await; + assert_eq!(resp.status(), StatusCode::OK); + let body = axum::body::to_bytes(resp.into_body(), usize::MAX) + .await + .unwrap(); + let out: serde_json::Value = serde_json::from_slice(&body).unwrap(); + let grant_id = out["grant_id"].as_str().expect("grant id returned"); + assert_eq!( + out["token_id"], grant_id, + "grant id IS the backing token id" + ); + assert!( + state.standing_service.is_active(grant_id), + "the minted mandate is LIVE in the shared registry" + ); + let cards = crate::api::handlers::capability::mandate_cards( + &state.standing_service, + &state.capability_manager, + ) + .await; + let card = cards + .mandates + .iter() + .find(|c| c.token_id == grant_id) + .expect("the minted mandate is listed"); + assert!(card.active); + assert_eq!(card.capsule, "vm-agent"); + assert_eq!(card.methods, vec!["send".to_string()]); + // The card SURFACES the binding (G-M4): bound = true, and the agent key round-trips. + assert!( + card.agent_bound, + "the card shows the mandate is agent-bound" + ); + assert_eq!(card.agent_pubkey.as_deref(), Some(agent.as_str())); + // Sprint 32: the responsible-entity liability binding round-trips onto the card. + assert_eq!( + card.responsible_entity.as_deref(), + Some("did:web:acme.example"), + "the card surfaces WHO is accountable" + ); + } + + /// The gateway mint enforces the SAME fail-closed guards as the API server (shared helper): + /// unknown action 400, empty methods 400, AUD-5 bare scheme wildcard 403, malformed agent key + /// 400 — and NONE of them mint anything. + #[tokio::test] + async fn issue_route_enforces_the_shared_guards() { + let dir = tempfile::tempdir().unwrap(); + let state = state_for(dir.path()); + let token_hdr = + super::super::issue_home_launch_token(dir.path(), MANDATES_CAPSULE_ID).unwrap(); + // A valid 64-hex agent key so downstream guards (wildcard, key-format) are the ones tested, + // not the new G-M4 bound-required check (which fires first when the key is absent). + let k = "\"agent_pubkey\":\"".to_string() + + &"ab".repeat(32) + + "\",\"responsible_entity\":\"did:web:acme.example\""; + let cases: Vec<(String, StatusCode)> = vec![ + ( + format!(r#"{{"capsule":"a","resource":"elastos://mail/send","action":"launch","methods":["m"],{k}}}"#), + StatusCode::BAD_REQUEST, + ), + ( + format!(r#"{{"capsule":"a","resource":"elastos://mail/send","action":"execute","methods":[],{k}}}"#), + StatusCode::BAD_REQUEST, + ), + ( + format!(r#"{{"capsule":"a","resource":"elastos://*","action":"execute","methods":["m"],{k}}}"#), + StatusCode::FORBIDDEN, + ), + ( + r#"{"capsule":"a","resource":"elastos://mail/send","action":"execute","methods":["m"],"agent_pubkey":"nothex","responsible_entity":"did:web:acme.example"}"#.to_string(), + StatusCode::BAD_REQUEST, + ), + // The web surface is narrower than the API: admin mints are refused server-side (P16), + // even case-shifted to dodge a naive string check. + ( + format!(r#"{{"capsule":"a","resource":"elastos://mail/send","action":"Admin","methods":["m"],{k}}}"#), + StatusCode::FORBIDDEN, + ), + // G-M4 (Sprint 20): an UNBOUND mandate (no agent key) is refused from the web surface — + // unbound is CLI-only. Server-side, not just the form. + ( + r#"{"capsule":"a","resource":"elastos://mail/send","action":"execute","methods":["m"]}"#.to_string(), + StatusCode::BAD_REQUEST, + ), + // Sprint 32: a bound mandate with NO responsible entity is refused from the shell + // (entity-less mandates are CLI-only) — server-side, an XSS in the frame can't skip it. + ( + format!(r#"{{"capsule":"a","resource":"elastos://mail/send","action":"execute","methods":["m"],"agent_pubkey":"{}"}}"#, "ab".repeat(32)), + StatusCode::BAD_REQUEST, + ), + // A malformed responsible entity (not a did: URI) fails closed at the shared core. + ( + format!(r#"{{"capsule":"a","resource":"elastos://mail/send","action":"execute","methods":["m"],"agent_pubkey":"{}","responsible_entity":"acme corp"}}"#, "ab".repeat(32)), + StatusCode::BAD_REQUEST, + ), + ( + r#"{"capsule":"a","resource":"elastos://mail/send","action":"execute","methods":["m"],"agent_pubkey":""}"#.to_string(), + StatusCode::BAD_REQUEST, + ), + ]; + for (body, expected) in &cases { + let resp = post_json( + mandate_router(state.clone()), + "/api/apps/mandates/standing-grants/issue", + Some(token_hdr.clone()), + body, + ) + .await; + assert_eq!(&resp.status(), expected, "guard for body {body}"); + } + assert!( + state.standing_service.list().is_empty(), + "every refused mint must mint NOTHING" + ); + } + + /// The agent-state view is fail-closed: no home-launch token ⇒ 401, no state leaks. + #[tokio::test] + async fn agent_state_route_requires_home_launch_token() { + let dir = tempfile::tempdir().unwrap(); + let app = mandate_router(state_for(dir.path())); + let denied = app + .oneshot( + Request::builder() + .uri("/api/apps/mandates/agent-state") + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(denied.status(), StatusCode::UNAUTHORIZED); + } + + /// With a valid token the operator sees ALL agents' durable state (spanning principals), as the + /// store holds it — the input_hash COMMITMENT, never content. + #[tokio::test] + async fn agent_state_route_reflects_the_store_across_principals() { + let dir = tempfile::tempdir().unwrap(); + // Two different agents write state directly into the store the route reads. + crate::agent_store::put_agent_state(dir.path(), "vm-a", "cursor", "cafe01", "g1", "i1") + .unwrap(); + crate::agent_store::put_agent_state(dir.path(), "vm-b", "flag", "beef02", "g2", "i2") + .unwrap(); + let app = mandate_router(state_for(dir.path())); + let token_hdr = + super::super::issue_home_launch_token(dir.path(), MANDATES_CAPSULE_ID).unwrap(); + let resp = app + .oneshot( + Request::builder() + .uri("/api/apps/mandates/agent-state") + .header(HOME_TOKEN_HEADER, token_hdr) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(resp.status(), StatusCode::OK); + let body = axum::body::to_bytes(resp.into_body(), usize::MAX) + .await + .unwrap(); + let json: serde_json::Value = serde_json::from_slice(&body).unwrap(); + let entries = json["entries"].as_array().expect("entries array"); + assert_eq!(entries.len(), 2, "operator sees BOTH agents' state"); + let a = entries.iter().find(|e| e["capsule"] == "vm-a").unwrap(); + assert_eq!(a["key"], "cursor"); + assert_eq!( + a["value_hash"], "cafe01", + "the commitment, verbatim from the store" + ); + assert_eq!(a["grant_id"], "g1", "attributed to the mandate"); + assert!(entries + .iter() + .any(|e| e["capsule"] == "vm-b" && e["key"] == "flag")); + } + + /// The list route is fail-closed: no home-launch token ⇒ 401, no data leaks. + #[tokio::test] + async fn list_route_requires_home_launch_token() { + let dir = tempfile::tempdir().unwrap(); + let app = mandate_router(state_for(dir.path())); + let denied = app + .oneshot( + Request::builder() + .uri("/api/apps/mandates/standing-grants") + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(denied.status(), StatusCode::UNAUTHORIZED); + } + + /// With a valid mandates home token, the list reads the SAME registry the manager issues + /// into — an issued mandate shows up, live. + #[tokio::test] + async fn list_route_reflects_the_shared_registry() { + let dir = tempfile::tempdir().unwrap(); + let state = state_for(dir.path()); + // Issue a mandate straight into the shared registry (the manager mints, the service elevates). + let token = state.capability_manager.grant( + "vm-agent", + ResourceId::new("elastos://mail/send".to_string()), + Action::Execute, + TokenConstraints::default(), + Some(elastos_common::SecureTimestamp::after_secs(3600)), + ); + let mut methods = std::collections::BTreeSet::new(); + methods.insert("send".to_string()); + let grant_id = state + .standing_service + .issue_from_token(&token, methods, None, None, None) + .unwrap(); + + let app = mandate_router(state); + let token_hdr = + super::super::issue_home_launch_token(dir.path(), MANDATES_CAPSULE_ID).unwrap(); + let resp = app + .oneshot( + Request::builder() + .uri("/api/apps/mandates/standing-grants") + .header(HOME_TOKEN_HEADER, token_hdr) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(resp.status(), StatusCode::OK); + let body = axum::body::to_bytes(resp.into_body(), usize::MAX) + .await + .unwrap(); + let json: serde_json::Value = serde_json::from_slice(&body).unwrap(); + let mandates = json["mandates"].as_array().expect("mandates array"); + let card = mandates + .iter() + .find(|m| m["token_id"] == grant_id) + .expect("the issued mandate is listed"); + assert_eq!(card["active"], true, "a just-issued mandate renders live"); + assert_eq!(card["revoked"], false); + assert_eq!(card["capsule"], "vm-agent"); + } + + /// A mandate killed ONLY by a key-rotation / `revoke_all` EPOCH advance (no individual token + /// revoke, no envelope flag) must NOT render "Live" on this liveness-proof surface. This is the + /// guardian+red-team fold-in: the `active` bit now consults `is_epoch_valid`, shared with the API + /// server via `mandate_cards`, so the two surfaces cannot drift. + #[tokio::test] + async fn list_route_marks_epoch_killed_mandate_dead() { + let dir = tempfile::tempdir().unwrap(); + let state = state_for(dir.path()); + let token = state.capability_manager.grant( + "vm-agent", + ResourceId::new("elastos://mail/send".to_string()), + Action::Execute, + TokenConstraints::default(), + None, + ); + let mut methods = std::collections::BTreeSet::new(); + methods.insert("send".to_string()); + let grant_id = state + .standing_service + .issue_from_token(&token, methods, None, None, None) + .unwrap(); + // Kill the whole epoch WITHOUT individually revoking the token or touching the envelope. + state.capability_manager.revoke_all("key rotation"); + // Sanity: the individual-revocation path is NOT what killed it — only the epoch advanced. + assert!( + !state + .capability_manager + .is_token_revoked(&TokenId::from_hex(&grant_id).unwrap()) + .await, + "revoke_all must not individually revoke — this test isolates the epoch path" + ); + + let app = mandate_router(state); + let token_hdr = + super::super::issue_home_launch_token(dir.path(), MANDATES_CAPSULE_ID).unwrap(); + let resp = app + .oneshot( + Request::builder() + .uri("/api/apps/mandates/standing-grants") + .header(HOME_TOKEN_HEADER, token_hdr) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(resp.status(), StatusCode::OK); + let body = axum::body::to_bytes(resp.into_body(), usize::MAX) + .await + .unwrap(); + let json: serde_json::Value = serde_json::from_slice(&body).unwrap(); + let card = json["mandates"] + .as_array() + .unwrap() + .iter() + .find(|m| m["token_id"] == grant_id) + .expect("the mandate is still listed"); + assert_eq!( + card["active"], false, + "an epoch-killed mandate never renders Live" + ); + assert_eq!(card["revoked"], true, "and it reads as revoked"); + } + + /// The receipt route is fail-closed too: no token ⇒ 401. + #[tokio::test] + async fn receipt_route_requires_home_launch_token() { + let dir = tempfile::tempdir().unwrap(); + let app = mandate_router(state_for(dir.path())); + let denied = app + .oneshot( + Request::builder() + .uri("/api/apps/mandates/mandate/deadbeef/receipt") + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(denied.status(), StatusCode::UNAUTHORIZED); + } + + /// The KILL SWITCH is gated like the reads: no home-launch token ⇒ 401 AND the mandate stays + /// live — an unauthenticated caller cannot kill (or probe) anything. + #[tokio::test] + async fn revoke_route_requires_home_launch_token_and_kills_nothing() { + let dir = tempfile::tempdir().unwrap(); + let state = state_for(dir.path()); + let token = state.capability_manager.grant( + "vm-agent", + ResourceId::new("elastos://mail/send".to_string()), + Action::Execute, + TokenConstraints::default(), + None, + ); + let mut methods = std::collections::BTreeSet::new(); + methods.insert("send".to_string()); + let grant_id = state + .standing_service + .issue_from_token(&token, methods, None, None, None) + .unwrap(); + + let app = mandate_router(state.clone()); + let denied = app + .oneshot( + Request::builder() + .method("POST") + .uri("/api/apps/mandates/standing-grants/revoke") + .header("content-type", "application/json") + .body(Body::from(format!("{{\"grant_id\":\"{grant_id}\"}}"))) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(denied.status(), StatusCode::UNAUTHORIZED); + assert!( + state.standing_service.is_active(&grant_id), + "an unauthenticated revoke must not kill the mandate" + ); + } + + /// The in-shell kill switch: revoke over the route kills the mandate (it reads dead in the + /// shared registry AND on the list), and a second pull reads `revoked:false` — idempotent, + /// honestly reported. + #[tokio::test] + async fn revoke_route_kills_the_mandate_and_is_idempotent() { + let dir = tempfile::tempdir().unwrap(); + let state = state_for(dir.path()); + let token = state.capability_manager.grant( + "vm-agent", + ResourceId::new("elastos://mail/send".to_string()), + Action::Execute, + TokenConstraints::default(), + None, + ); + let mut methods = std::collections::BTreeSet::new(); + methods.insert("send".to_string()); + let grant_id = state + .standing_service + .issue_from_token(&token, methods, None, None, None) + .unwrap(); + assert!(state.standing_service.is_active(&grant_id)); + + let app = mandate_router(state.clone()); + let token_hdr = + super::super::issue_home_launch_token(dir.path(), MANDATES_CAPSULE_ID).unwrap(); + let revoke = |hdr: String, gid: String| { + let app = app.clone(); + async move { + let resp = app + .oneshot( + Request::builder() + .method("POST") + .uri("/api/apps/mandates/standing-grants/revoke") + .header(HOME_TOKEN_HEADER, hdr) + .header("content-type", "application/json") + .body(Body::from(format!("{{\"grant_id\":\"{gid}\"}}"))) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(resp.status(), StatusCode::OK); + let body = axum::body::to_bytes(resp.into_body(), usize::MAX) + .await + .unwrap(); + serde_json::from_slice::(&body).unwrap() + } + }; + + // First pull: kills a live mandate. + let first = revoke(token_hdr.clone(), grant_id.clone()).await; + assert_eq!( + first["revoked"], true, + "a live mandate is killed by this call" + ); + assert!( + !state.standing_service.is_active(&grant_id), + "the envelope is dead in the SHARED registry" + ); + + // The list surface agrees — never renders the killed mandate Live. + let cards = crate::api::handlers::capability::mandate_cards( + &state.standing_service, + &state.capability_manager, + ) + .await; + let card = cards + .mandates + .iter() + .find(|c| c.token_id == grant_id) + .expect("still listed (an operator surface shows what was killed)"); + assert!(!card.active, "killed mandate never renders Live"); + assert!(card.revoked); + + // Second pull: idempotent, honestly `false` (nothing live was killed). + let second = revoke(token_hdr, grant_id).await; + assert_eq!(second["revoked"], false, "double-revoke reads false"); + } + + /// A malformed grant id is rejected 400 BEFORE any kill path runs (fail-closed canonicalization). + #[tokio::test] + async fn revoke_route_rejects_malformed_id() { + let dir = tempfile::tempdir().unwrap(); + let app = mandate_router(state_for(dir.path())); + let token_hdr = + super::super::issue_home_launch_token(dir.path(), MANDATES_CAPSULE_ID).unwrap(); + let resp = app + .oneshot( + Request::builder() + .method("POST") + .uri("/api/apps/mandates/standing-grants/revoke") + .header(HOME_TOKEN_HEADER, token_hdr) + .header("content-type", "application/json") + .body(Body::from(r#"{"grant_id":"not-hex"}"#)) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(resp.status(), StatusCode::BAD_REQUEST); + } + + /// The Money panel routes are fail-closed twice over (Sprint 31): no home-launch token ⇒ 401 + /// (nothing leaks, nothing provisions); with a token but NO wired rail ⇒ 503 (absence + /// reported, never an empty fabrication). + #[tokio::test] + async fn money_routes_are_gated_and_honest_about_an_unwired_rail() { + let dir = tempfile::tempdir().unwrap(); + let state = state_for(dir.path()); // pay_rail: None + let app = mandate_router(state); + // No token ⇒ 401 on all three. + for (method, uri, body) in [ + ("GET", "/api/apps/mandates/money", String::new()), + ( + "POST", + "/api/apps/mandates/spend-budget", + r#"{"fresh_passkey_token":"x","input":{"capsule":"vm-a","limit":5}}"#.into(), + ), + ( + "POST", + "/api/apps/mandates/payments/reconcile", + r#"{"fresh_passkey_token":"x","input":{"idempotency_key":"flint-x","charged":false}}"#.into(), + ), + ] { + let req = Request::builder() + .method(method) + .uri(uri) + .header("content-type", "application/json") + .body(Body::from(body)) + .unwrap(); + let resp = app.clone().oneshot(req).await.unwrap(); + assert_eq!(resp.status(), StatusCode::UNAUTHORIZED, "{method} {uri}"); + } + // Token but unwired rail ⇒ 503. + let token_hdr = + super::super::issue_home_launch_token(dir.path(), MANDATES_CAPSULE_ID).unwrap(); + let resp = app + .clone() + .oneshot( + Request::builder() + .uri("/api/apps/mandates/money") + .header(HOME_TOKEN_HEADER, token_hdr) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(resp.status(), StatusCode::SERVICE_UNAVAILABLE); + } + + /// End-to-end over the SHELL surface: provision a durable cap, see it (with pending + /// visibility) on the money view, and resolve an indeterminate payment not-charged — the + /// refund lands on the SAME meter the pay gate enforces with, exactly once. + #[tokio::test] + async fn money_panel_provisions_and_reconciles_over_the_shared_rail() { + let dir = tempfile::tempdir().unwrap(); + let (capability_manager, standing_service) = manager_and_service(); + let meter = Arc::new( + elastos_runtime::primitives::spend::SpendMeter::open_durable( + dir.path().join("spend_meter.json"), + ) + .unwrap(), + ); + let ledger = Arc::new( + crate::payment_ledger::PaymentLedger::open_durable( + dir.path().join("payment_ledger.json"), + ) + .unwrap(), + ); + let state = MandateApiState { + standing_service, + capability_manager, + data_dir: dir.path().to_path_buf(), + pay_rail: Some(crate::api::server::PayRail { + meter: meter.clone(), + provider: Arc::new(crate::intent_executor::MockPaymentProvider::default()), + ledger: ledger.clone(), + drm_confirmer: None, + quote_cache: Arc::default(), + negotiator: None, + }), + spent_fresh_money_tokens: Arc::default(), + marketplace_quote_cache: Arc::default(), + }; + let app = mandate_router(state); + // Sprint 33: money writes each need their OWN fresh passkey verification. + let (token_hdr, fresh) = money_write_tokens(dir.path(), 3); + + // Provision via the shell surface — the shared core applies + attests. + let resp = post_json( + app.clone(), + "/api/apps/mandates/spend-budget", + Some(token_hdr.clone()), + &money_body(&fresh[0], r#"{"capsule":"vm-ap-agent","limit":500}"#), + ) + .await; + assert_eq!(resp.status(), StatusCode::OK); + assert_eq!( + meter.remaining("vm-ap-agent"), + 500, + "the ENFORCING meter holds the cap" + ); + + // An indeterminate payment holds 200 and files a pending obligation (as the pay path + // would): reserve on the meter + record on the ledger. + meter.try_debit("vm-ap-agent", 200).unwrap(); + assert!(ledger.record( + "flint-abc", + "vm-ap-agent", + "acme-vendor", + 200, + crate::payment_ledger::PaymentStatus::Pending, + "timeout" + )); + + // The money view projects both: the budget with pending visibility + the work list. + let resp = app + .clone() + .oneshot( + Request::builder() + .uri("/api/apps/mandates/money") + .header(HOME_TOKEN_HEADER, token_hdr.clone()) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(resp.status(), StatusCode::OK); + let body = axum::body::to_bytes(resp.into_body(), usize::MAX) + .await + .unwrap(); + let json: serde_json::Value = serde_json::from_slice(&body).unwrap(); + let budget = &json["budgets"][0]; + assert_eq!(budget["capsule"], "vm-ap-agent"); + assert_eq!(budget["remaining"], 300); + assert_eq!(budget["pending_units"], 200, "held-unconfirmed is distinct"); + assert_eq!(json["pending"][0]["idempotency_key"], "flint-abc"); + + // Reconcile not-charged over the shell surface: refund exactly once, 409 on retry. + let resp = post_json( + app.clone(), + "/api/apps/mandates/payments/reconcile", + Some(token_hdr.clone()), + &money_body( + &fresh[1], + r#"{"idempotency_key":"flint-abc","charged":false}"#, + ), + ) + .await; + assert_eq!(resp.status(), StatusCode::OK); + let body = axum::body::to_bytes(resp.into_body(), usize::MAX) + .await + .unwrap(); + let out: serde_json::Value = serde_json::from_slice(&body).unwrap(); + assert_eq!(out["refunded"], true); + assert_eq!( + meter.remaining("vm-ap-agent"), + 500, + "the refund landed on the shared meter" + ); + let retry = post_json( + app, + "/api/apps/mandates/payments/reconcile", + Some(token_hdr), + &money_body( + &fresh[2], + r#"{"idempotency_key":"flint-abc","charged":false}"#, + ), + ) + .await; + assert_eq!( + retry.status(), + StatusCode::CONFLICT, + "resolves exactly once" + ); + assert_eq!(meter.remaining("vm-ap-agent"), 500, "no double refund"); + } + + /// Council S31 G-F1: the WEB surface's cap ceiling — a provision above it is refused 403 + /// server-side (an XSS in the frame cannot provision an unbounded cap) and provisions NOTHING; + /// at-or-below the ceiling still works. The raw consent-broker API carries no ceiling. + #[tokio::test] + async fn web_spend_budget_is_ceiling_bound_server_side() { + let dir = tempfile::tempdir().unwrap(); + let (capability_manager, standing_service) = manager_and_service(); + let meter = Arc::new( + elastos_runtime::primitives::spend::SpendMeter::open_durable( + dir.path().join("spend_meter.json"), + ) + .unwrap(), + ); + let state = MandateApiState { + standing_service, + capability_manager, + data_dir: dir.path().to_path_buf(), + pay_rail: Some(crate::api::server::PayRail { + meter: meter.clone(), + provider: Arc::new(crate::intent_executor::MockPaymentProvider::default()), + ledger: Arc::new(crate::payment_ledger::PaymentLedger::new()), + drm_confirmer: None, + quote_cache: Arc::default(), + negotiator: None, + }), + spent_fresh_money_tokens: Arc::default(), + marketplace_quote_cache: Arc::default(), + }; + let app = mandate_router(state); + let (token_hdr, fresh) = money_write_tokens(dir.path(), 2); + let over = WEB_MAX_SPEND_CAP_DEFAULT + 1; + let resp = post_json( + app.clone(), + "/api/apps/mandates/spend-budget", + Some(token_hdr.clone()), + &money_body( + &fresh[0], + &format!(r#"{{"capsule":"vm-xss","limit":{over}}}"#), + ), + ) + .await; + assert_eq!( + resp.status(), + StatusCode::FORBIDDEN, + "above the ceiling is refused" + ); + assert_eq!( + meter.snapshot("vm-xss"), + None, + "the refused provision set NOTHING" + ); + let resp = post_json( + app, + "/api/apps/mandates/spend-budget", + Some(token_hdr), + &money_body( + &fresh[1], + &format!(r#"{{"capsule":"vm-ok","limit":{WEB_MAX_SPEND_CAP_DEFAULT}}}"#), + ), + ) + .await; + assert_eq!( + resp.status(), + StatusCode::OK, + "at the ceiling still provisions" + ); + } + + /// Council S31 red-team F2 regression: the gateway money routes must emit NO + /// Access-Control-Allow-Origin for a foreign Origin — a future refactor adding permissive + /// CORS here would hand cross-origin pages the preflight pass the CSRF analysis relies on + /// being absent. + #[tokio::test] + async fn money_routes_emit_no_cors_allowance_for_foreign_origins() { + let dir = tempfile::tempdir().unwrap(); + let app = mandate_router(state_for(dir.path())); + let resp = app + .oneshot( + Request::builder() + .method("OPTIONS") + .uri("/api/apps/mandates/payments/reconcile") + .header("origin", "https://evil.example") + .header("access-control-request-method", "POST") + .header("access-control-request-headers", "x-elastos-home-token") + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert!( + resp.headers().get("access-control-allow-origin").is_none(), + "no ACAO for a foreign origin — the preflight must fail" + ); + } + + /// Sprint 33 ratchet (a): the standing 12h launch token ALONE can no longer move money. + /// Before this sprint the exact failure was that a leaked launch URL could provision budgets + /// for its whole 12h life; now a money write without a fresh passkey verification — empty, + /// or a stale/unbound token — is refused and provisions NOTHING. + #[tokio::test] + async fn money_write_with_the_standing_token_alone_is_refused() { + let dir = tempfile::tempdir().unwrap(); + let (capability_manager, standing_service) = manager_and_service(); + let meter = Arc::new( + elastos_runtime::primitives::spend::SpendMeter::open_durable( + dir.path().join("spend_meter.json"), + ) + .unwrap(), + ); + let state = MandateApiState { + standing_service, + capability_manager, + data_dir: dir.path().to_path_buf(), + pay_rail: Some(crate::api::server::PayRail { + meter: meter.clone(), + provider: Arc::new(crate::intent_executor::MockPaymentProvider::default()), + ledger: Arc::new(crate::payment_ledger::PaymentLedger::new()), + drm_confirmer: None, + quote_cache: Arc::default(), + negotiator: None, + }), + spent_fresh_money_tokens: Arc::default(), + marketplace_quote_cache: Arc::default(), + }; + let app = mandate_router(state); + let (standing, _) = money_write_tokens(dir.path(), 0); + + // No fresh verification at all. + let resp = post_json( + app.clone(), + "/api/apps/mandates/spend-budget", + Some(standing.clone()), + &money_body("", r#"{"capsule":"vm-a","limit":5}"#), + ) + .await; + assert_eq!( + resp.status(), + StatusCode::UNAUTHORIZED, + "empty fresh token refused" + ); + + // The standing token ITSELF is not a fresh verification (it is not proof-bound) — a + // session-rider replaying the credential they already hold gains nothing. + let resp = post_json( + app.clone(), + "/api/apps/mandates/spend-budget", + Some(standing.clone()), + &money_body(&standing, r#"{"capsule":"vm-a","limit":5}"#), + ) + .await; + assert_eq!( + resp.status(), + StatusCode::UNAUTHORIZED, + "unbound token refused" + ); + assert_eq!(meter.snapshot("vm-a"), None, "nothing was provisioned"); + + // Reads stay on the standing session alone — no regression, no passkey friction. + let resp = app + .oneshot( + Request::builder() + .uri("/api/apps/mandates/money") + .header(HOME_TOKEN_HEADER, standing) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!( + resp.status(), + StatusCode::OK, + "reads need no fresh verification" + ); + } + + /// Sprint 33 ratchets (b)+(c): one fresh passkey verification authorizes exactly ONE money + /// write. Replaying it on the SAME verb is refused (b), and spending it on set-budget then + /// presenting it to reconcile is refused too (c) — single-use consumption subsumes cross-verb + /// binding: the assertion cannot authorize a second write of ANY kind. + #[tokio::test] + async fn fresh_passkey_verification_is_single_use_across_money_verbs() { + let dir = tempfile::tempdir().unwrap(); + let (capability_manager, standing_service) = manager_and_service(); + let meter = Arc::new( + elastos_runtime::primitives::spend::SpendMeter::open_durable( + dir.path().join("spend_meter.json"), + ) + .unwrap(), + ); + let ledger = Arc::new(crate::payment_ledger::PaymentLedger::new()); + let state = MandateApiState { + standing_service, + capability_manager, + data_dir: dir.path().to_path_buf(), + pay_rail: Some(crate::api::server::PayRail { + meter: meter.clone(), + provider: Arc::new(crate::intent_executor::MockPaymentProvider::default()), + ledger: ledger.clone(), + drm_confirmer: None, + quote_cache: Arc::default(), + negotiator: None, + }), + spent_fresh_money_tokens: Arc::default(), + marketplace_quote_cache: Arc::default(), + }; + let app = mandate_router(state); + let (standing, fresh) = money_write_tokens(dir.path(), 1); + + // First write spends the verification. + let resp = post_json( + app.clone(), + "/api/apps/mandates/spend-budget", + Some(standing.clone()), + &money_body(&fresh[0], r#"{"capsule":"vm-once","limit":50}"#), + ) + .await; + assert_eq!( + resp.status(), + StatusCode::OK, + "the first write is authorized" + ); + assert_eq!(meter.remaining("vm-once"), 50); + + // (b) Replay on the SAME verb: refused, and the cap is NOT re-set. + let resp = post_json( + app.clone(), + "/api/apps/mandates/spend-budget", + Some(standing.clone()), + &money_body(&fresh[0], r#"{"capsule":"vm-once","limit":999}"#), + ) + .await; + assert_eq!( + resp.status(), + StatusCode::FORBIDDEN, + "replay on the same verb refused" + ); + assert_eq!( + meter.remaining("vm-once"), + 50, + "the replayed write applied NOTHING" + ); + + // (c) Cross-verb: the spent verification cannot authorize reconcile either. The refusal + // is at the authorization gate — before any ledger lookup. + meter.try_debit("vm-once", 10).unwrap(); + assert!(ledger.record( + "flint-xv", + "vm-once", + "vendor", + 10, + crate::payment_ledger::PaymentStatus::Pending, + "timeout" + )); + let resp = post_json( + app.clone(), + "/api/apps/mandates/payments/reconcile", + Some(standing), + &money_body( + &fresh[0], + r#"{"idempotency_key":"flint-xv","charged":false}"#, + ), + ) + .await; + assert_eq!( + resp.status(), + StatusCode::FORBIDDEN, + "cross-verb replay refused" + ); + assert_eq!( + meter.remaining("vm-once"), + 40, + "no refund was applied by the refused call" + ); + } + + /// Sprint 33 ratchet (cookie transport): the HttpOnly path-scoped cookie authorizes the + /// surface exactly like the header — reads work over it — but a cookie-authorized WRITE + /// must carry the anti-CSRF marker header (a cookie is ambient; the custom header is what a + /// cross-site page cannot send without a preflight this gateway refuses). + #[tokio::test] + async fn cookie_transport_reads_work_and_writes_demand_the_csrf_marker() { + let dir = tempfile::tempdir().unwrap(); + let app = mandate_router(state_for(dir.path())); + let (standing, _) = money_write_tokens(dir.path(), 0); + let cookie = format!("{MANDATES_SESSION_COOKIE}={standing}"); + + // Read over the cookie alone: authorized. + let resp = app + .clone() + .oneshot( + Request::builder() + .uri("/api/apps/mandates/standing-grants") + .header("cookie", &cookie) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(resp.status(), StatusCode::OK, "cookie authorizes reads"); + + // Cookie-authorized WRITE without the marker: refused as potential CSRF. + let revoke_body = format!(r#"{{"grant_id":"{}"}}"#, "0".repeat(32)); + let resp = app + .clone() + .oneshot( + Request::builder() + .method("POST") + .uri("/api/apps/mandates/standing-grants/revoke") + .header("content-type", "application/json") + .header("cookie", &cookie) + .body(Body::from(revoke_body.clone())) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!( + resp.status(), + StatusCode::FORBIDDEN, + "a cookie-authorized write without the app marker is refused" + ); + + // Same write WITH the marker: passes the gate (the unknown mandate honestly reads + // `revoked:false` — the kill switch stays reachable over the cookie). + let resp = app + .oneshot( + Request::builder() + .method("POST") + .uri("/api/apps/mandates/standing-grants/revoke") + .header("content-type", "application/json") + .header("cookie", &cookie) + .header(MANDATES_APP_MARKER_HEADER, "1") + .body(Body::from(revoke_body)) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!( + resp.status(), + StatusCode::OK, + "the marker admits the same-origin write" + ); + } + + /// Council S33 guardian F1 (the fold's ship-blocker): the single-use guard keys on the + /// CANONICAL assertion the signature covers, never the raw token string. A spent fresh token + /// RE-ENCODED into a byte-different string (pretty-printed JSON, same envelope) still + /// VERIFIES as the same assertion — and must still read as SPENT. Before the fix the guard + /// hashed the raw string, so one WebAuthn ceremony re-encoded N ways authorized N money + /// writes. The 403 (not 401) on the replay is the proof the re-encoding passed verification + /// and the GUARD — not the signature check — is what refused it. + #[tokio::test] + async fn a_re_encoded_spent_verification_is_still_spent() { + let dir = tempfile::tempdir().unwrap(); + let (capability_manager, standing_service) = manager_and_service(); + let meter = Arc::new( + elastos_runtime::primitives::spend::SpendMeter::open_durable( + dir.path().join("spend_meter.json"), + ) + .unwrap(), + ); + let state = MandateApiState { + standing_service, + capability_manager, + data_dir: dir.path().to_path_buf(), + pay_rail: Some(crate::api::server::PayRail { + meter: meter.clone(), + provider: Arc::new(crate::intent_executor::MockPaymentProvider::default()), + ledger: Arc::new(crate::payment_ledger::PaymentLedger::new()), + drm_confirmer: None, + quote_cache: Arc::default(), + negotiator: None, + }), + spent_fresh_money_tokens: Arc::default(), + marketplace_quote_cache: Arc::default(), + }; + let app = mandate_router(state); + let (standing, fresh) = money_write_tokens(dir.path(), 1); + + // Spend the verification on a legitimate write. + let resp = post_json( + app.clone(), + "/api/apps/mandates/spend-budget", + Some(standing.clone()), + &money_body(&fresh[0], r#"{"capsule":"vm-malleate","limit":50}"#), + ) + .await; + assert_eq!(resp.status(), StatusCode::OK); + assert_eq!(meter.remaining("vm-malleate"), 50); + + // Re-encode the SAME token into a byte-different string: decode → parse → pretty-print + // → re-encode. The signature still verifies (it covers the canonical payload, which is + // unchanged); only the transport bytes differ. + use base64::Engine as _; + let bytes = base64::engine::general_purpose::URL_SAFE_NO_PAD + .decode(&fresh[0]) + .unwrap(); + let value: serde_json::Value = serde_json::from_slice(&bytes).unwrap(); + let pretty = serde_json::to_vec_pretty(&value).unwrap(); + assert_ne!(pretty, bytes, "the re-encoding must be byte-different"); + let re_encoded = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(&pretty); + assert_ne!(re_encoded, fresh[0]); + + let resp = post_json( + app, + "/api/apps/mandates/spend-budget", + Some(standing), + &money_body(&re_encoded, r#"{"capsule":"vm-malleate","limit":999}"#), + ) + .await; + assert_eq!( + resp.status(), + StatusCode::FORBIDDEN, + "the re-encoded replay must read SPENT (403), not unverified (401)" + ); + assert_eq!( + meter.remaining("vm-malleate"), + 50, + "the replay applied NOTHING" + ); + } + + /// Council S33 red-team F1: a refusal PROVABLY BEFORE any money effect (here the web + /// ceiling) re-credits the ceremony — the operator's one verification still buys their one + /// write — and the verification is spent only when a write actually reaches the core. + #[tokio::test] + async fn a_pre_effect_refusal_re_credits_the_fresh_verification() { + let dir = tempfile::tempdir().unwrap(); + let (capability_manager, standing_service) = manager_and_service(); + let meter = Arc::new( + elastos_runtime::primitives::spend::SpendMeter::open_durable( + dir.path().join("spend_meter.json"), + ) + .unwrap(), + ); + let state = MandateApiState { + standing_service, + capability_manager, + data_dir: dir.path().to_path_buf(), + pay_rail: Some(crate::api::server::PayRail { + meter: meter.clone(), + provider: Arc::new(crate::intent_executor::MockPaymentProvider::default()), + ledger: Arc::new(crate::payment_ledger::PaymentLedger::new()), + drm_confirmer: None, + quote_cache: Arc::default(), + negotiator: None, + }), + spent_fresh_money_tokens: Arc::default(), + marketplace_quote_cache: Arc::default(), + }; + let app = mandate_router(state); + let (standing, fresh) = money_write_tokens(dir.path(), 1); + let over = WEB_MAX_SPEND_CAP_DEFAULT + 1; + + // Refused over the ceiling — pre-effect, so the ceremony is re-credited. + let resp = post_json( + app.clone(), + "/api/apps/mandates/spend-budget", + Some(standing.clone()), + &money_body( + &fresh[0], + &format!(r#"{{"capsule":"vm-cred","limit":{over}}}"#), + ), + ) + .await; + assert_eq!(resp.status(), StatusCode::FORBIDDEN); + assert_eq!(meter.snapshot("vm-cred"), None, "nothing was provisioned"); + + // The SAME verification now authorizes the corrected write. + let resp = post_json( + app.clone(), + "/api/apps/mandates/spend-budget", + Some(standing.clone()), + &money_body(&fresh[0], r#"{"capsule":"vm-cred","limit":100}"#), + ) + .await; + assert_eq!( + resp.status(), + StatusCode::OK, + "the re-credited verification still works" + ); + assert_eq!(meter.remaining("vm-cred"), 100); + + // …and having bought its one applied write, it is now spent for good. + let resp = post_json( + app, + "/api/apps/mandates/spend-budget", + Some(standing), + &money_body(&fresh[0], r#"{"capsule":"vm-cred","limit":101}"#), + ) + .await; + assert_eq!( + resp.status(), + StatusCode::FORBIDDEN, + "one applied write, then spent" + ); + assert_eq!(meter.remaining("vm-cred"), 100); + } + + /// Honest absence: a well-formed token with no durable records ⇒ 404, never a fabricated receipt. + #[tokio::test] + async fn receipt_route_reports_absence_as_404() { + let dir = tempfile::tempdir().unwrap(); + let app = mandate_router(state_for(dir.path())); + let token_hdr = + super::super::issue_home_launch_token(dir.path(), MANDATES_CAPSULE_ID).unwrap(); + // A syntactically valid (16-byte / 32-hex) token id that was never issued. + let unknown = "0".repeat(32); + let resp = app + .oneshot( + Request::builder() + .uri(format!("/api/apps/mandates/mandate/{unknown}/receipt")) + .header(HOME_TOKEN_HEADER, token_hdr) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(resp.status(), StatusCode::NOT_FOUND); + } + // ────────────────────────── Marketplace panel (Sprint 38) ────────────────────────── + + /// The marketplace read is gated exactly like every other route: no launch token ⇒ 401. + #[tokio::test] + async fn marketplace_route_requires_home_launch_token() { + let dir = tempfile::tempdir().unwrap(); + let app = mandate_router(state_for(dir.path())); + let denied = app + .oneshot( + Request::builder() + .uri("/api/apps/mandates/marketplace") + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(denied.status(), StatusCode::UNAUTHORIZED); + } + + /// No rail wired ⇒ 503, honestly unwired — same posture as the Money panel. + #[tokio::test] + async fn marketplace_without_a_rail_reads_unwired() { + let dir = tempfile::tempdir().unwrap(); + let app = mandate_router(state_for(dir.path())); + let token_hdr = + super::super::issue_home_launch_token(dir.path(), MANDATES_CAPSULE_ID).unwrap(); + let resp = app + .oneshot( + Request::builder() + .uri("/api/apps/mandates/marketplace") + .header(HOME_TOKEN_HEADER, token_hdr) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(resp.status(), StatusCode::SERVICE_UNAVAILABLE); + } + + /// The panel is a pure PROJECTION: pay-mandates scope the asset list (non-pay mandates never + /// appear), and the buys table renders the ledger's records with the HONEST wording — a + /// broadcast-accepted buy reads "awaiting chain confirmation", never anything like + /// "purchased"; a confirmed one carries its tx; a refusal reads refused. + #[tokio::test] + async fn marketplace_projects_pay_mandates_and_ledger_buys_with_honest_wording() { + use crate::payment_ledger::{PaymentLedger, PaymentStatus}; + use elastos_runtime::primitives::spend::SpendMeter; + + let dir = tempfile::tempdir().unwrap(); + let mut state = state_for(dir.path()); + let meter = Arc::new(SpendMeter::new()); + let ledger = Arc::new(PaymentLedger::new()); + state.pay_rail = Some(crate::api::server::PayRail { + meter, + provider: Arc::new(crate::intent_executor::MockPaymentProvider::default()), + ledger: ledger.clone(), + drm_confirmer: None, + quote_cache: Arc::default(), + negotiator: None, + }); + + // A pay-mandate for asset QmMovie… + let pay_token = state.capability_manager.grant( + "vm-shopper", + ResourceId::new("elastos://runtime/pay/QmMovie".to_string()), + Action::Execute, + TokenConstraints::default(), + None, + ); + let mut pay_methods = std::collections::BTreeSet::new(); + pay_methods.insert("runtime.pay".to_string()); + let pay_grant = state + .standing_service + .issue_from_token(&pay_token, pay_methods, None, None, None) + .unwrap(); + // …and a NON-pay mandate that must never surface as a marketplace asset. + let mail_token = state.capability_manager.grant( + "vm-agent", + ResourceId::new("elastos://mail/send".to_string()), + Action::Execute, + TokenConstraints::default(), + None, + ); + let mut mail_methods = std::collections::BTreeSet::new(); + mail_methods.insert("send".to_string()); + state + .standing_service + .issue_from_token(&mail_token, mail_methods, None, None, None) + .unwrap(); + + // Ledger truth: a broadcast-pending DRM buy, a chain-confirmed one, and a refusal. + assert!(ledger.record_with_token( + "flint-pending", + "vm-shopper", + "QmMovie", + 5, + PaymentStatus::Pending, + "drm:tx=0xAB;op=0xop;tid=7", + Some(&pay_grant), + )); + assert!(ledger.record_with_token( + "flint-confirmed", + "vm-shopper", + "QmMovie", + 5, + PaymentStatus::ResolvedCharged, + "drm:tx=0xCD;op=0xop;tid=7", + Some(&pay_grant), + )); + assert!(ledger.record( + "flint-refused", + "vm-shopper", + "QmMovie", + 999, + PaymentStatus::NotCharged, + "refused by spend cap", + )); + + // Pre-populate the quote cache so the projection is fully deterministic (no chain). + state.marketplace_quote_cache.lock().unwrap().insert( + "QmMovie".to_string(), + crate::market_quote::MarketQuoteSlot { + quoted_at: now_ts(), + quote: Some(MarketQuote { + price: Some("5000000".to_string()), + pay_token: Some("0xUSDC".to_string()), + supply: Some(3), + error: None, + }), + }, + ); + + let app = mandate_router(state); + let token_hdr = + super::super::issue_home_launch_token(dir.path(), MANDATES_CAPSULE_ID).unwrap(); + let resp = app + .oneshot( + Request::builder() + .uri("/api/apps/mandates/marketplace") + .header(HOME_TOKEN_HEADER, token_hdr) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(resp.status(), StatusCode::OK); + let body = axum::body::to_bytes(resp.into_body(), usize::MAX) + .await + .unwrap(); + let json: serde_json::Value = serde_json::from_slice(&body).unwrap(); + + // Assets: exactly the pay-mandate's asset, quote served CACHE-FIRST (no chain read). + let assets = json["assets"].as_array().unwrap(); + assert_eq!( + assets.len(), + 1, + "only pay-mandates scope marketplace assets" + ); + assert_eq!(assets[0]["asset"], "QmMovie"); + assert_eq!(assets[0]["mandates"][0], pay_grant); + assert_eq!( + assets[0]["quote"]["price"], "5000000", + "the quote is served from the TTL cache — a panel refresh is not a chain read" + ); + + // Buys: honest wording per state, tx extracted from the DRM rail note. + let buys = json["buys"].as_array().unwrap(); + assert_eq!(buys.len(), 3); + let by_state = |st: &str| { + buys.iter() + .find(|b| b["state"] == st) + .unwrap_or_else(|| panic!("no {st} row")) + }; + let pending = by_state("pending"); + assert_eq!(pending["detail"], "broadcast — awaiting chain confirmation"); + assert_eq!(pending["tx"], "0xAB"); + assert!( + !pending["detail"].as_str().unwrap().contains("purchas"), + "a broadcast is NEVER worded as a purchase" + ); + let confirmed = by_state("confirmed"); + assert_eq!(confirmed["detail"], "confirmed on-chain"); + assert_eq!(confirmed["tx"], "0xCD"); + assert_eq!(confirmed["mandate"], pay_grant); + let refused = by_state("refused"); + assert_eq!(refused["detail"], "refused — nothing charged"); + assert_eq!(refused["amount"], 999); + assert!( + refused.get("tx").is_none(), + "no tx on a never-broadcast refusal" + ); + } + /// Council S38 fold (guardian F1 + red-team F1): quote coverage ROTATES — cache hits are + /// free (they never consume a fresh-read slot), so with more assets than the per-view + /// fresh-read cap, the first view reads the cap's worth and the SECOND view (finding those + /// cached) reads the rest: no asset is permanently starved of a quote. + #[tokio::test] + async fn quote_coverage_rotates_instead_of_starving_the_tail() { + use crate::payment_ledger::PaymentLedger; + use elastos_runtime::primitives::spend::SpendMeter; + + let dir = tempfile::tempdir().unwrap(); + let mut state = state_for(dir.path()); + state.pay_rail = Some(crate::api::server::PayRail { + meter: Arc::new(SpendMeter::new()), + provider: Arc::new(crate::intent_executor::MockPaymentProvider::default()), + ledger: Arc::new(PaymentLedger::new()), + drm_confirmer: None, + quote_cache: Arc::default(), + negotiator: None, + }); + // MARKET_MAX_QUOTED_ASSETS + 2 assets, each behind an active pay-mandate. + for i in 0..(MARKET_MAX_QUOTED_ASSETS + 2) { + let token = state.capability_manager.grant( + "vm-shopper", + ResourceId::new(format!("elastos://runtime/pay/Qm{i:02}")), + Action::Execute, + TokenConstraints::default(), + None, + ); + let mut methods = std::collections::BTreeSet::new(); + methods.insert("runtime.pay".to_string()); + state + .standing_service + .issue_from_token(&token, methods, None, None, None) + .unwrap(); + } + + let app = mandate_router(state.clone()); + let token_hdr = + super::super::issue_home_launch_token(dir.path(), MANDATES_CAPSULE_ID).unwrap(); + let view = |app: Router, hdr: String| async move { + let resp = app + .oneshot( + Request::builder() + .uri("/api/apps/mandates/marketplace") + .header(HOME_TOKEN_HEADER, hdr) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(resp.status(), StatusCode::OK); + let body = axum::body::to_bytes(resp.into_body(), usize::MAX) + .await + .unwrap(); + serde_json::from_slice::(&body).unwrap() + }; + + // View 1: the cap's worth of assets get fresh reads (in CI the chain read fails fast, so + // they land as bounded error quotes — still QUOTED outcomes); exactly 2 are over-cap. + let first = view(app.clone(), token_hdr.clone()).await; + let over_cap = |j: &serde_json::Value| { + j["assets"] + .as_array() + .unwrap() + .iter() + .filter(|a| a["unquoted_over_cap"] == true) + .count() + }; + assert_eq!( + over_cap(&first), + 2, + "the tail waits, stated — never silently dropped" + ); + + // View 2: the first batch is CACHED (free), so the tail gets the fresh-read slots. + let second = view(app, token_hdr).await; + assert_eq!( + over_cap(&second), + 0, + "cache hits are free — the rotation reaches every asset by the second view" + ); + assert!( + second["assets"] + .as_array() + .unwrap() + .iter() + .all(|a| a["quote"].is_object()), + "every asset ends up with a quote outcome (live terms or a bounded error)" + ); + } + + /// Council S38 fold (red-team F2): a live PENDING buy can never be pushed out of the buys + /// table by a flood of newer settled entries — pending is always shown; only the settled + /// tail is windowed, and the window is STATED via buys_total. + #[tokio::test] + async fn a_pending_buy_is_never_truncated_by_a_flood_of_settled_entries() { + use crate::payment_ledger::{PaymentLedger, PaymentStatus}; + use elastos_runtime::primitives::spend::SpendMeter; + + let dir = tempfile::tempdir().unwrap(); + let mut state = state_for(dir.path()); + let ledger = Arc::new(PaymentLedger::new()); + state.pay_rail = Some(crate::api::server::PayRail { + meter: Arc::new(SpendMeter::new()), + provider: Arc::new(crate::intent_executor::MockPaymentProvider::default()), + ledger: ledger.clone(), + drm_confirmer: None, + quote_cache: Arc::default(), + negotiator: None, + }); + + // The OLDEST entry is a live pending obligation… + assert!(ledger.record_with_token( + "flint-obligation", + "vm-shopper", + "QmMovie", + 5, + PaymentStatus::Pending, + "drm:tx=0xAB;op=0xop;tid=7", + None, + )); + // …then a flood of newer settled entries, more than the window. + for i in 0..(MARKET_BUYS_LIMIT + 10) { + assert!(ledger.record( + &format!("flint-noise-{i}"), + "vm-flooder", + "QmOther", + 1, + PaymentStatus::NotCharged, + "refused", + )); + } + + let app = mandate_router(state); + let token_hdr = + super::super::issue_home_launch_token(dir.path(), MANDATES_CAPSULE_ID).unwrap(); + let resp = app + .oneshot( + Request::builder() + .uri("/api/apps/mandates/marketplace") + .header(HOME_TOKEN_HEADER, token_hdr) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(resp.status(), StatusCode::OK); + let body = axum::body::to_bytes(resp.into_body(), usize::MAX) + .await + .unwrap(); + let json: serde_json::Value = serde_json::from_slice(&body).unwrap(); + let buys = json["buys"].as_array().unwrap(); + assert!( + buys.iter() + .any(|b| b["state"] == "pending" && b["asset"] == "QmMovie"), + "the live obligation is ALWAYS visible, however many settled entries arrive" + ); + assert_eq!( + json["buys_total"].as_u64().unwrap() as usize, + MARKET_BUYS_LIMIT + 11, + "the window is stated, never silent" + ); + assert!( + buys.len() <= MARKET_BUYS_LIMIT + 1, + "the settled tail stays windowed (pending rides on top of the cap)" + ); + } +} diff --git a/elastos/crates/elastos-server/src/api/gateway_server.rs b/elastos/crates/elastos-server/src/api/gateway_server.rs index 310e81f9..bb3bda95 100644 --- a/elastos/crates/elastos-server/src/api/gateway_server.rs +++ b/elastos/crates/elastos-server/src/api/gateway_server.rs @@ -8,6 +8,7 @@ use tokio::net::TcpListener; use super::{gateway_router, GatewayState, GATEWAY_VERSION}; +#[allow(clippy::too_many_arguments)] pub async fn start_gateway_server( addr: &str, provider_registry: Option>, @@ -15,7 +16,11 @@ pub async fn start_gateway_server( data_dir: PathBuf, spend_policy: Option, shared_audit_log: Option>, + standing_service: Option>, + capability_manager: Option>, + pay_rail: Option, ) -> anyhow::Result<()> { + let data_dir_for_mandates = data_dir.clone(); let state = GatewayState { provider_registry, identity_manager: Arc::new(OnceLock::new()), @@ -26,7 +31,35 @@ pub async fn start_gateway_server( audit_log: super::seed_gateway_audit_log(shared_audit_log), spend_policy, }; - let app = gateway_router(state); + let mut app = gateway_router(state); + // Merge the mandates sub-router (reads + the revoke kill switch) only when BOTH the shared + // registry and the capability manager are present — the manager owns the durable audit chain + // the receipt export, the token-revocation liveness check, AND the attested revoke all need. + // Without it the app would be crippled, so we fail closed to "no live mandate data" rather + // than half-wire it. The sub-router carries its own state, so the ~40 GatewayState + // construction sites are left untouched. + if let (Some(standing_service), Some(capability_manager)) = + (standing_service, capability_manager) + { + app = app.merge(super::gateway_mandates::mandate_router( + super::gateway_mandates::MandateApiState { + standing_service, + capability_manager, + data_dir: data_dir_for_mandates, + // The SAME meter+ledger Arcs the executor's pay gate enforces with (the stores' + // single-opener flocks forbid a second opener by construction). `None` ⇒ the + // Money panel routes answer 503, honestly unwired. + // The panel's quote cache IS the rail's (same Arc): the Marketplace panel and + // the runtime.market_quote affordance share one single-flight fan-out bound. + marketplace_quote_cache: pay_rail + .as_ref() + .map(|r| r.quote_cache.clone()) + .unwrap_or_default(), + pay_rail, + spent_fresh_money_tokens: Arc::default(), + }, + )); + } let listener = TcpListener::bind(addr).await?; let advertised = advertised_gateway_urls(addr); println!("ElastOS Gateway v{}", GATEWAY_VERSION); diff --git a/elastos/crates/elastos-server/src/api/handlers/capability.rs b/elastos/crates/elastos-server/src/api/handlers/capability.rs index e3d9c244..529d8bea 100755 --- a/elastos/crates/elastos-server/src/api/handlers/capability.rs +++ b/elastos/crates/elastos-server/src/api/handlers/capability.rs @@ -18,6 +18,7 @@ use elastos_runtime::approval::{self, ApprovalDecision}; use elastos_runtime::capability::manager::ValidationError; use elastos_runtime::capability::{ pending::{AffordanceBinding, PendingRequestStore}, + token::TokenId, Action, AffordanceGrantReceiptV1, CapabilityManager, CapabilityToken, EnvelopeCheck, GrantDuration, IntentDeclarationV1, PolicyEvaluator, PolicyOutcome, ResourceId, StandingGrantService, TokenConstraints, @@ -33,6 +34,19 @@ pub struct CapabilityState { /// The standing-grant service (issue/revoke/dispatch for unsupervised agent acts), backed by the /// manager's own key + audit log. Shared so every shell-only verb hits the same grant registry. pub standing_service: Arc, + /// Performs a dispatched intent and reports what was ACTUALLY done — the independent "done" the + /// reconciliation checks against the declaration. An unregistered method declines (⇒ + /// `Undelivered`), so an authorized-but-unperformed intent is never a fabricated `Matched`. + pub intent_executor: Arc, + /// The spend meter backing `runtime.pay` — the SAME instance the executor's pay closure debits, + /// so the operator provisioning surface and the enforcement path can never disagree. `None` when + /// no payment rail is wired (the fail-closed default): provisioning is then refused honestly + /// (503) rather than accepting a budget nothing enforces. + pub spend_meter: Option>, + /// The payment ledger (Sprint 30) — the SAME instance the pay closure records into: the + /// reconciliation surface reads/resolves exactly what enforcement wrote. `None` when pay is + /// unwired. + pub payment_ledger: Option>, } // === Request Capability === @@ -59,15 +73,17 @@ pub struct RequestCapabilityInput { #[derive(Debug, Serialize)] pub struct RequestCapabilityOutput { - /// Status: "pending", "granted", or "auto_denied" + /// Status: "pending" (queued for user approval) or "denied" (policy refusal). These strings + /// are the wire contract — clients branch on them. pub status: String, /// Request ID (if pending) #[serde(skip_serializing_if = "Option::is_none")] pub request_id: Option, - /// Capability token (if auto-granted) + /// Reserved for an auto-grant path; the request endpoint never auto-grants today (every + /// grant goes through user approval), so this is currently always absent. #[serde(skip_serializing_if = "Option::is_none")] pub token: Option, - /// Reason (if auto-denied) + /// Reason (if denied) #[serde(skip_serializing_if = "Option::is_none")] pub reason: Option, } @@ -75,32 +91,15 @@ pub struct RequestCapabilityOutput { /// POST /api/capability/request /// /// Request a capability token. Returns immediately with either: -/// - status: "pending" + request_id (needs user approval) -/// - status: "granted" + token (auto-granted) -/// - status: "auto_denied" + reason (policy rejection) +/// - status: "pending" + request_id (queued for user approval) +/// - status: "denied" + reason (policy refusal — overbroad resource, system-only backend, ...) pub async fn request_capability( State(state): State, Extension(session): Extension, Json(input): Json, ) -> Result, (StatusCode, String)> { - // Parse action - let action = match input.action.to_lowercase().as_str() { - "read" => Action::Read, - "write" => Action::Write, - "execute" => Action::Execute, - "delete" => Action::Delete, - "message" => Action::Message, - "admin" => Action::Admin, - _ => { - return Err(( - StatusCode::BAD_REQUEST, - format!( - "Invalid action: {}. Expected: read, write, execute, delete, message, admin", - input.action - ), - )); - } - }; + // Parse action (the ONE parser — no hand-copied action set; S50 guardian F4). + let action = parse_action(&input.action)?; if !is_supported_resource_scheme(&input.resource) { return Err(( @@ -221,22 +220,17 @@ pub struct RequestStatusOutput { // === Validate And Consume (W2 step 7) === -/// Parse an action string into an [`Action`], or a 400 listing the allowed set. +/// Parse an action string into an [`Action`], or a 400 listing the allowed set. Delegates to the +/// ONE parser (`Action`'s `FromStr`) so the accepted set cannot drift from the enum (S50 guardian F4). fn parse_action(raw: &str) -> Result { - match raw.to_lowercase().as_str() { - "read" => Ok(Action::Read), - "write" => Ok(Action::Write), - "execute" => Ok(Action::Execute), - "delete" => Ok(Action::Delete), - "message" => Ok(Action::Message), - "admin" => Ok(Action::Admin), - _ => Err(( + ::from_str(raw).map_err(|_| { + ( StatusCode::BAD_REQUEST, format!( "Invalid action: {raw}. Expected: read, write, execute, delete, message, admin" ), - )), - } + ) + }) } /// Map a [`ValidationError`] to a fail-closed response with a DISTINCT, safe code @@ -891,6 +885,25 @@ pub async fn revoke_all_capabilities( ) -> Result, (StatusCode, String)> { let new_epoch = state.capability_manager.revoke_all(&input.reason); + // The envelope side of the mass kill: the epoch advance kills every backing TOKEN, but the + // standing-grant registry knows nothing of epochs — without this, an epoch-dead mandate keeps + // rendering (and, once dispatch is wired, dispatching) as LIVE. A registry persistence failure + // surfaces, and the error claims only what is established (guardian F2): `advance_epoch` is + // itself best-effort-persisted and returns the OLD epoch on failure without signaling the + // handler — so under a correlated disk failure "all tokens dead" would be a guess, not a fact. + // A mass kill whose envelopes may resurrect as "Live" cards on restart must not report clean + // success either way. + state.standing_service.revoke_all().map_err(|e| { + ( + StatusCode::INTERNAL_SERVER_ERROR, + format!( + "epoch advance requested (epoch now {new_epoch}) but the mandate registry could \ + not record the envelope revokes — retry, and verify the epoch actually \ + advanced: {e}" + ), + ) + })?; + // Mark all granted requests as revoked, fail-closed on the audit records (AUD-3): // the epoch increment above already invalidated the tokens, but an incomplete // attestation is surfaced rather than silently lost. @@ -1062,61 +1075,270 @@ pub struct IssueStandingGrantInput { /// Optional time-to-live in seconds; omitted ⇒ no expiry (until revoked). #[serde(default)] pub ttl_secs: Option, + /// Optional AUTHORIZED AGENT ed25519 verifying key (hex). When set, ONLY intents signed by + /// this key may act under the mandate — the audit attribution is the real agent. Omitted ⇒ + /// capsule-string-only authorization (weaker; see KNOWN_GAPS G-M4). + #[serde(default)] + pub agent_pubkey: Option, + /// Optional per-mandate dispatch-rate budget: acts per `MANDATE_DISPATCH_WINDOW_SECS` window + /// (Sprint 22 — rate is a first-class grant property, like scope/expiry/agent). Omitted ⇒ the + /// global default (`MANDATE_DISPATCH_LIMIT`). Zero is refused (a zero-rate mandate authorizes + /// nothing; revoke is the kill switch, not a budget). + #[serde(default)] + pub dispatch_limit: Option, + /// The RESPONSIBLE ENTITY (Sprint 32): the DID the OPERATOR DECLARES accountable for every act + /// under this mandate — the EU-AI-Act liability attribution. Validated (`did:` URI, bounded) and + /// recorded verbatim in the SIGNED CapabilityGrant chain event, so the portable receipt proves + /// WHICH entity the operator DECLARED accountable. OPERATOR-ASSERTED, NOT ATTESTED: the runtime + /// does not resolve the DID or obtain the named entity's counter-signature — a receipt is proof + /// of the operator's declaration, not the entity's consent (entity counter-signing is a tracked + /// gap). Optional on the raw API/CLI (back-compat); the web mint surface REQUIRES it (gateway + /// narrowing, like the agent key). + #[serde(default)] + pub responsible_entity: Option, } #[derive(Debug, Serialize)] pub struct IssueStandingGrantOutput { /// The standing grant id (the backing token's id) — revoke or dispatch against this. pub grant_id: String, + /// The backing capability token's id — identical to `grant_id`, surfaced explicitly because it + /// is the key for the mandate's audit trail (`export_mandate_receipt_for_capability`). + pub token_id: String, } -/// POST /api/standing-grants/issue (shell-only) +/// Validate the operator-asserted responsible-entity DID (Sprint 32, council F3/F6). SYNTACTIC +/// only — anti-garbage, bounded, injection-safe; it does NOT authenticate or resolve the DID (that +/// would falsely imply the entity consented — council F2). `None`/blank ⇒ `Ok(None)` (the field is +/// optional on the API/CLI). Shape: `did::`, ≤256 ASCII +/// chars, charset {alnum : . - _ %} (path/query/fragment excluded — an identifier, not a URL). +pub(crate) fn validate_responsible_entity(raw: Option<&str>) -> Result, String> { + let did = match raw.map(str::trim) { + None | Some("") => return Ok(None), + Some(d) => d, + }; + let bad = |m: &str| { + Err(format!( + "responsible_entity must be a did: URI (e.g. did:web:acme.example), \u{2264}256 chars, \ + DID charset \u{2014} {m}. It is recorded verbatim on the signed chain and must not be \ + garbage" + )) + }; + if did.len() > elastos_runtime::capability::RESPONSIBLE_ENTITY_MAX_LEN { + return bad("too long"); + } + // The same shared syntactic bound the service-layer choke points re-apply — one home for the + // charset, so the surfaces can never drift. + if !elastos_runtime::capability::responsible_entity_syntax_ok(did) { + return bad("illegal character"); + } + // did:: — method is a non-empty run of lowercase ASCII alphanumerics; msid is + // non-empty. splitn(3) keeps any further colons inside the method-specific id. + let mut parts = did.splitn(3, ':'); + match (parts.next(), parts.next(), parts.next()) { + (Some("did"), Some(method), Some(msid)) + if !method.is_empty() + && method + .chars() + .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit()) + && !msid.is_empty() => + { + Ok(Some(did.to_string())) + } + _ => bad("expected did:: with a lowercase method and a non-empty id"), + } +} + +/// Issue a mandate — the ONE shared mint path, used by the API server's [`issue_standing_grant`] +/// and the gateway's mandates shell app (`api::gateway::gateway_mandates`), so the fail-closed +/// guards (action whitelist, non-empty methods, AUD-5 overbroad-wildcard refusal, agent-key +/// validation, durable-before-visible issuance) can never drift between surfaces. /// -/// Issue a standing grant for unsupervised agent dispatch. Mints a real signed capability token -/// for (capsule, resource, action, ttl) — the cryptographic root — then derives and stores the -/// standing envelope with the authorized method set. Fail-closed on an unknown action or empty -/// method set. -pub async fn issue_standing_grant( - State(state): State, - Json(input): Json, -) -> Result, (StatusCode, String)> { - let action = match input.action.to_lowercase().as_str() { - "read" => Action::Read, - "write" => Action::Write, - "execute" => Action::Execute, - "delete" => Action::Delete, - "message" => Action::Message, - "admin" => Action::Admin, - _ => { +/// Mints a real signed capability token for (capsule, resource, action, ttl) — the cryptographic +/// root — then derives and stores the standing envelope with the authorized method set. +pub async fn issue_mandate( + standing_service: &StandingGrantService, + capability_manager: &CapabilityManager, + input: IssueStandingGrantInput, +) -> Result { + let action = parse_action(&input.action)?; + if input.methods.is_empty() { + return Err(( + StatusCode::BAD_REQUEST, + "a standing grant must authorize at least one method".to_string(), + )); + } + // AUD-5 defense-in-depth (mirrors grant_request): refuse to mint a bare scheme-level wildcard + // mandate — it would prefix-match every resource under the scheme. + if is_overbroad_grant_resource(&input.resource) { + return Err(( + StatusCode::FORBIDDEN, + "scheme-level wildcard mandates are not permitted; scope to at least one path segment" + .to_string(), + )); + } + // Validate the optional agent key up front: a present-but-malformed key must fail closed, never + // silently degrade to an unbound (weaker) mandate. + let agent_pubkey = match input.agent_pubkey.as_deref().map(str::trim) { + None | Some("") => None, + Some(hex_key) => { + let bytes = hex::decode(hex_key).map_err(|e| { + ( + StatusCode::BAD_REQUEST, + format!("agent_pubkey not hex: {e}"), + ) + })?; + let arr: [u8; 32] = bytes.as_slice().try_into().map_err(|_| { + ( + StatusCode::BAD_REQUEST, + format!( + "agent_pubkey must be 32 bytes (64 hex chars), got {}", + bytes.len() + ), + ) + })?; + // Reject a key that is not a real, non-weak ed25519 point (council, Sprint 20 red-team + // F1): the identity / low-order points parse as valid 32 bytes but a forged signature + // validates for them under any message — a mandate "bound" to such a key would be + // satisfiable by anyone, an effectively-UNBOUND mandate wearing a "bound" badge. A + // non-canonical or small-order key is refused here so a bound mandate always means a + // real, single-agent binding. (The dispatch gate also uses verify_strict as belt.) + let vk = ed25519_dalek::VerifyingKey::from_bytes(&arr).map_err(|_| { + ( + StatusCode::BAD_REQUEST, + "agent_pubkey is not a valid ed25519 public key".to_string(), + ) + })?; + if vk.is_weak() { + return Err(( + StatusCode::BAD_REQUEST, + "agent_pubkey is a weak (small-order) ed25519 key — its binding would be \ + forgeable; use a real agent key" + .to_string(), + )); + } + Some(hex::encode(arr)) + } + }; + // Confidentiality binding (Sprint 25 council F2): a mandate authorizing `runtime.state_get` READS + // the principal's durable state. An UNBOUND mandate (agent_pubkey None) skips the gate's + // WrongAgent check, so it is protected only by token-id secrecy — anyone who learns the token + // could read the state under the capsule string. Require an agent key for a state_get mandate, + // fail-closed at the mint. (The gateway shell already binds every mint; this closes the + // raw-API/CLI path for the confidentiality-sensitive read. The write side `state_put` keeps its + // pre-existing accepted unbound contract — a symmetric tightening is tracked in KNOWN_GAPS G-M4.) + if agent_pubkey.is_none() && input.methods.iter().any(|m| m == "runtime.state_get") { + return Err(( + StatusCode::BAD_REQUEST, + "a mandate authorizing runtime.state_get must bind an agent key — an unbound state-read \ + mandate would expose the principal's durable state to anyone who learns its token id" + .to_string(), + )); + } + // The dispatch budget must be in [1, MAX]. Zero would mint a mandate that LOOKS live on the + // card yet denies every act (revoke is the kill switch, not a budget); an unclamped limit would + // uncap the fsync-flood bound (council red-team F2 / guardian F3). This is the friendly 400; + // issue_from_token re-checks the same invariant at the service layer for any non-HTTP caller. + if let Some(n) = input.dispatch_limit { + if n == 0 || n > elastos_runtime::capability::MANDATE_DISPATCH_LIMIT_MAX { return Err(( StatusCode::BAD_REQUEST, format!( - "Invalid action: {}. Expected: read, write, execute, delete, message, admin", - input.action + "dispatch_limit must be between 1 and {} acts per window (got {}); omit it for \ + the default. To stop a mandate acting, revoke it.", + elastos_runtime::capability::MANDATE_DISPATCH_LIMIT_MAX, + n ), )); } - }; - if input.methods.is_empty() { - return Err(( - StatusCode::BAD_REQUEST, - "a standing grant must authorize at least one method".to_string(), - )); } + // Sprint 32: the liability attribution is recorded VERBATIM on the signed chain, so a + // present-but-malformed entity fails CLOSED (garbage is worse than none). SYNTACTIC + // anti-garbage + injection-safety ONLY — it does NOT authenticate the DID (that would falsely + // imply the entity consented — council F2). Re-validated at the service choke point too so a + // non-HTTP caller can't smuggle an unbounded blob onto the chain (council F6). + let responsible_entity = validate_responsible_entity(input.responsible_entity.as_deref()) + .map_err(|msg| (StatusCode::BAD_REQUEST, msg))?; let expiry = input .ttl_secs .map(elastos_common::SecureTimestamp::after_secs); + // Provability floor (Sprint 24 council F1): grant_durable's "on the chain" is only as durable as + // the audit log's backing. A MEMORY-ONLY log makes emit() succeed with no disk write, while the + // standing registry IS persisted — so a restart would restore the mandate without its grant + // record (the F1 gap, via the audit door). Surface that misconfiguration loudly rather than + // silently mint an un-provable "durable" mandate. (A hard refusal would break the legitimate + // ephemeral/dev mode where nothing is cross-restart durable anyway; the durable-custody + // deployment sets ELASTOS_AUDIT_LOG_PATH and this never fires.) + if capability_manager.audit_log().log_path().is_none() { + tracing::warn!( + capsule = %input.capsule, + "minting a mandate into a MEMORY-ONLY audit log — its grant record is not cross-restart \ + durable; set ELASTOS_AUDIT_LOG_PATH for provable custody (Sprint 24 F1)" + ); + } // Mint a real signed token (the cryptographic root), then elevate it to a standing grant. - let token = state.capability_manager.grant( - &input.capsule, - ResourceId::new(input.resource), - action, - TokenConstraints::default(), - expiry, - ); + // FAIL-CLOSED mint (Sprint 24, closes Sprint 23 council F1): the signed durable CapabilityGrant + // must land on the audit chain BEFORE the mandate exists — so a mandate, whose registry entry is + // now retention-pruned (Sprint 23), can never exist without a provable grant event. If the audit + // write fails, no token is returned and no mandate is issued (symmetric with the fail-closed + // revoke). A best-effort mint could leave a since-pruned mandate with no trace anywhere. + let token = capability_manager + .grant_durable( + &input.capsule, + ResourceId::new(input.resource), + action, + TokenConstraints::default(), + expiry, + responsible_entity.clone(), + ) + .map_err(|e| { + ( + StatusCode::INTERNAL_SERVER_ERROR, + format!("mandate grant could not be durably recorded on the audit chain — not issued: {e}"), + ) + })?; let methods: std::collections::BTreeSet = input.methods.into_iter().collect(); - let grant_id = state.standing_service.issue_from_token(&token, methods); - Ok(Json(IssueStandingGrantOutput { grant_id })) + // Durable-before-visible (G-M5): a mandate that cannot be recorded to the persistent registry + // is NOT issued — the operator retries into a working store rather than holding a grant that + // silently evaporates on the next restart. + let grant_id = standing_service + .issue_from_token( + &token, + methods, + agent_pubkey, + input.dispatch_limit, + responsible_entity, + ) + .map_err(|e| { + // Reverse-failure honesty (Sprint 24 council F2): the CapabilityGrant already landed on + // the chain, but the mandate did NOT get issued. Emit a compensating (best-effort) + // revoke so the chain reads "granted, then aborted" — an honest completed lifecycle — + // rather than an orphan grant a receipt-verifier would read as a live, never-revoked + // mandate. Best-effort: the grant is already durable; this can only make the record more + // honest, never less. + capability_manager.audit_log().capability_revoke( + token.id(), + "issuance aborted: standing-registry persist failed", + ); + ( + StatusCode::INTERNAL_SERVER_ERROR, + format!("mandate could not be durably recorded — not issued: {e}"), + ) + })?; + let token_id = token.id().to_string(); + Ok(IssueStandingGrantOutput { grant_id, token_id }) +} + +/// POST /api/standing-grants/issue (shell-only) +/// +/// Issue a standing grant for unsupervised agent dispatch — see [`issue_mandate`] for the shared +/// fail-closed mint path. +pub async fn issue_standing_grant( + State(state): State, + Json(input): Json, +) -> Result, (StatusCode, String)> { + let out = issue_mandate(&state.standing_service, &state.capability_manager, input).await?; + Ok(Json(out)) } #[derive(Debug, Deserialize)] @@ -1132,19 +1354,480 @@ pub struct RevokeStandingGrantOutput { pub revoked: bool, } +/// Revoke a mandate — the ONE shared kill path, used by the API server's [`revoke_standing_grant`] +/// and the gateway's mandates shell app (`api::gateway::gateway_mandates`), so the fail-closed +/// ORDER of the kill can never drift between surfaces. +/// +/// Fail-closed AND durably attested. The grant id IS the backing capability token's id, and killing +/// only the in-memory envelope would leave the mandate's audit trail showing it live forever — so +/// this first revokes the BACKING TOKEN through the manager (which emits the signed +/// `CapabilityRevoke` record BEFORE mutating, per AUD-3: if the durable write fails, the revoke +/// ABORTS and the error surfaces rather than a revoke existing with no record), then kills the +/// standing envelope so the dispatcher denies every not-yet-started act. The mandate's receipt +/// (`export_mandate_receipt_for_capability`) thereafter carries the revoke. `reason` names the +/// surface that pulled the switch — it lands verbatim in the signed audit record. +pub async fn revoke_mandate( + standing_service: &StandingGrantService, + capability_manager: &CapabilityManager, + grant_id: &str, + reason: &str, +) -> Result { + let token_id = TokenId::from_hex(grant_id.trim()).map_err(|e| { + ( + StatusCode::BAD_REQUEST, + format!("grant_id is not a valid token id: {e}"), + ) + })?; + // Durable custody first (emit-before-mutate): a revoke that cannot be signed onto the audit + // chain does not happen — mirroring revoke_capability. The envelope stays live so the failure + // is loud and re-runnable, never a silent half-revoke the receipt can't prove. + capability_manager + .revoke(token_id, reason) + .await + .map_err(|e| { + ( + StatusCode::INTERNAL_SERVER_ERROR, + format!("revoke could not be durably attested: {e}"), + ) + })?; + // Kill the envelope by the CANONICAL id (the parsed token's lowercase-hex Display form — the + // exact key the registry stores). Keying off the caller's raw string would let an UPPERCASE + // spelling revoke the token yet miss the envelope, leaving the dispatch path live. A registry + // persistence failure surfaces loudly; the error claims exactly what the manager guarantees + // (guardian F1): the signed CapabilityRevoke RECORD is durable (emit-before-mutate) and the + // token is revoked in THIS runtime, but the token-state persist itself is best-effort + // (`persist_revoked_tokens` logs, never errors) — so under a failing disk the honest claim is + // "attested + revoked here", not "durably revoked". The caller retries (idempotent) rather + // than trusting a revoke the registry may forget. + standing_service.revoke(&token_id.to_string()).map_err(|e| { + ( + StatusCode::INTERNAL_SERVER_ERROR, + format!( + "revoke durably attested (signed audit record) and token revoked in this \ + runtime, but the mandate registry could not record the envelope revoke — \ + retry: {e}" + ), + ) + }) +} + /// POST /api/standing-grants/revoke (shell-only) — the autonomy kill switch. /// -/// Revoke a standing grant by id, fail-closed. After this, every not-yet-started act under the -/// grant is denied (the dispatcher re-reads the grant each time). Returns whether a live grant -/// was revoked by this call. +/// See [`revoke_mandate`] for the fail-closed semantics (durably attest FIRST, then kill the +/// envelope). pub async fn revoke_standing_grant( State(state): State, Json(input): Json, ) -> Result, (StatusCode, String)> { - let revoked = state.standing_service.revoke(&input.grant_id); + let revoked = revoke_mandate( + &state.standing_service, + &state.capability_manager, + &input.grant_id, + "standing grant revoked via API", + ) + .await?; Ok(Json(RevokeStandingGrantOutput { revoked })) } +// === Spend budgets (Sprint 28) — the operator provisioning surface for the runtime.pay cap === + +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct SetSpendBudgetInput { + /// The capsule (agent identity) whose money cap is being provisioned — the same string the pay + /// closure debits (`intent.capsule`), held to the same slug bound the executor enforces. + pub capsule: String, + /// The TOTAL budget (cumulative cap). Lowering below what is already spent clamps remaining to + /// zero — it never refunds silently. + pub limit: u64, +} + +#[derive(Debug, Serialize)] +pub struct SpendBudgetOutput { + pub capsule: String, + pub limit: u64, + pub spent: u64, + pub remaining: u64, + /// True when the enforcing meter is POISONED (a persist failed post-publish): every payment + /// and every provisioning change is refusing fail-closed until the process is restarted + /// (council S29 F5/F10 — the ops surface for `SpendMeter::is_poisoned`). + pub poisoned: bool, + /// Units of this capsule's cap held by INDETERMINATE payments awaiting rail reconciliation + /// (Sprint 30, council S29 RT-F4): spend the operator must NOT treat as confirmed — and must + /// reconcile BEFORE raising the cap, or the raise can authorize real spend beyond intent. + pub pending_units: u64, + /// Count of this capsule's pending (indeterminate) payments. + pub pending_count: u64, +} + +/// POST /api/spend-budgets (shell-only) — provision (or re-set) a capsule's money cap. +/// +/// This is real operator AUTHORITY, so it is held to the mandate discipline: +/// - **Same-instance enforcement:** the meter here IS the one the executor's pay closure debits — +/// what the operator sets is exactly what is enforced, by construction. +/// - **Fail-closed without a rail:** no wired payment rail ⇒ no meter ⇒ 503. A budget nothing +/// enforces is never accepted. +/// - **Durable-only:** a money cap on a meter that refills across restart is a lie; a non-durable +/// meter refuses provisioning (503) rather than accepting a cap it cannot keep. +/// - **Attested:** the budget change lands on the signed audit chain as a `ConfigChange` +/// (`spend_budget:{capsule}`, old → new). Apply-then-attest with rollback: the event is emitted +/// only AFTER the budget is durably in force (the chain never claims a cap that isn't real), and +/// if the emit fails the budget is rolled back — a first-time provision is fully REMOVED, never +/// left as a provisioned-at-zero artifact (council S28 F7). Under a single failure no unattested +/// cap stays in force. Residuals, stated honestly (council S28 F2/F5): if the ROLLBACK itself +/// cannot persist (a correlated failure — audit chain and meter share `data_dir`), the cap the +/// operator requested may remain durably in force UNATTESTED; that double failure is surfaced +/// loudly (distinct 500 naming it, error log, best-effort attestation) — never silently +/// discarded. And a pay racing the failed attestation may appear on-chain under a cap whose +/// `ConfigChange` never landed (the payment's own receipt still lands; apply-then-attest is the +/// honest ordering — the inverse would put a FALSE claim on the chain). +pub async fn set_spend_budget( + State(state): State, + Json(input): Json, +) -> Result, (StatusCode, String)> { + let Some(meter) = &state.spend_meter else { + return Err(( + StatusCode::SERVICE_UNAVAILABLE, + "no payment rail is wired — a spend budget nothing enforces is refused".to_string(), + )); + }; + set_spend_budget_core( + meter, + state.payment_ledger.as_deref(), + state.capability_manager.audit_log(), + input, + ) + .map(Json) +} + +/// The ONE shared provisioning path (Sprint 31): the API server's shell route and the gateway's +/// Mandates-app route both delegate here, so the fail-closed guards (durable-only, slug bound, +/// apply-then-attest with true rollback, loud double-failure) can never drift between surfaces — +/// the same one-source-of-truth rule as `issue_mandate`/`revoke_mandate`. +pub(crate) fn set_spend_budget_core( + meter: &elastos_runtime::primitives::spend::SpendMeter, + ledger: Option<&crate::payment_ledger::PaymentLedger>, + audit_log: &elastos_runtime::primitives::audit::AuditLog, + input: SetSpendBudgetInput, +) -> Result { + if !meter.is_durable() { + return Err(( + StatusCode::SERVICE_UNAVAILABLE, + "the spend meter is not durable — a money cap that refills on restart is refused" + .to_string(), + )); + } + if !crate::intent_executor::valid_slug_1_64(&input.capsule) { + return Err(( + StatusCode::BAD_REQUEST, + "capsule must be a 1-64 char slug (the identity the pay gate debits)".to_string(), + )); + } + // The PRIOR limit comes back from set_budget itself, read under the meter's write lock in the + // same critical section as the mutation (council S28 F6) — the one linearizable old-value the + // attestation and the rollback can both trust. Two lock-free snapshot() reads here would let + // concurrent provisions attest the same stale "old". + let prior_limit = meter.set_budget(&input.capsule, input.limit).map_err(|e| { + ( + StatusCode::INTERNAL_SERVER_ERROR, + format!("budget not applied (durable persist failed, rolled back): {e}"), + ) + })?; + let config_change = || elastos_runtime::primitives::audit::AuditEvent::ConfigChange { + timestamp: elastos_runtime::primitives::SecureTimestamp::now(), + setting: format!("spend_budget:{}", input.capsule), + old_value: prior_limit + .map(|l| l.to_string()) + .unwrap_or_else(|| "unprovisioned".to_string()), + new_value: input.limit.to_string(), + }; + if let Err(e) = audit_log.emit(config_change()) { + // No unattested cap stays in force: restore the prior limit, or fully REMOVE a first-time + // provision (never a provisioned-at-zero artifact the chain never granted — F7). + let rollback = match prior_limit { + Some(limit) => meter.set_budget(&input.capsule, limit).map(|_| ()), + None => meter.remove_budget(&input.capsule).map(|_| ()), + }; + if let Err(rb) = rollback { + // DOUBLE FAILURE (council S28 F2, correlated: chain and meter share data_dir): the cap + // the operator asked for is durably in force but its attestation never landed and the + // rollback could not persist. Surface it loudly and distinctly — the operator must + // intervene — and try the attestation once more best-effort (the chain may recover). + tracing::error!( + capsule = %input.capsule, + limit = input.limit, + "spend budget applied but NOT attested, and the rollback could not persist \ + ({rb}) — an unattested money cap may be in force; operator intervention required" + ); + audit_log.emit_best_effort(config_change()); + return Err(( + StatusCode::INTERNAL_SERVER_ERROR, + format!( + "budget applied but could NOT be attested on the audit chain ({e}), and the \ + rollback could not persist ({rb}) — the cap may remain in force unattested; \ + operator intervention required" + ), + )); + } + return Err(( + StatusCode::INTERNAL_SERVER_ERROR, + format!("budget change could not be attested on the audit chain — rolled back: {e}"), + )); + } + let snap = meter.snapshot(&input.capsule).ok_or(( + StatusCode::INTERNAL_SERVER_ERROR, + "budget vanished after set".to_string(), + ))?; + let (pending_units, pending_count) = ledger + .map(|l| l.pending_for(&input.capsule)) + .unwrap_or((0, 0)); + Ok(SpendBudgetOutput { + capsule: input.capsule, + limit: snap.limit, + spent: snap.spent, + remaining: snap.remaining, + poisoned: meter.is_poisoned(), + pending_units, + pending_count: pending_count as u64, + }) +} + +/// GET /api/spend-budgets/:capsule (shell-only) — the read-only projection of one capsule's money +/// cap (limit / spent / remaining), straight off the enforcing meter. 404 when unprovisioned. +pub async fn get_spend_budget( + State(state): State, + Path(capsule): Path, +) -> Result, (StatusCode, String)> { + let Some(meter) = &state.spend_meter else { + return Err(( + StatusCode::SERVICE_UNAVAILABLE, + "no payment rail is wired".to_string(), + )); + }; + let snap = meter.snapshot(&capsule).ok_or(( + StatusCode::NOT_FOUND, + "no spend budget provisioned for this capsule".to_string(), + ))?; + let (pending_units, pending_count) = state + .payment_ledger + .as_ref() + .map(|l| l.pending_for(&capsule)) + .unwrap_or((0, 0)); + Ok(Json(SpendBudgetOutput { + capsule, + limit: snap.limit, + spent: snap.spent, + remaining: snap.remaining, + poisoned: meter.is_poisoned(), + pending_units, + pending_count: pending_count as u64, + })) +} + +// === Payment reconciliation (Sprint 30) — resolving INDETERMINATE rail outcomes === + +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct ReconcilePaymentInput { + /// The pending payment's idempotency key (from the decline reason / the pending list) — the + /// handle the operator looked up ON THE RAIL before calling this. + pub idempotency_key: String, + /// The rail's verdict: `true` = the charge DID post (spend stands); `false` = it did NOT + /// (the reservation is refunded). + pub charged: bool, +} + +#[derive(Debug, Serialize)] +pub struct ReconcilePaymentOutput { + pub idempotency_key: String, + pub capsule: String, + pub amount: u64, + /// The terminal status the entry resolved to. + pub status: String, + /// True iff the reservation was refunded AND the refund is durably in force. + pub refunded: bool, + /// Honest caveats the operator must read (refund persist failure, attestation failure). + #[serde(skip_serializing_if = "Option::is_none")] + pub warning: Option, +} + +/// GET /api/payments/pending (shell-only) — the reconciliation work list: every INDETERMINATE +/// payment (reservation held, outcome unknown), oldest first, with the idempotency key to look up +/// on the rail. Read-only projection of the ledger the pay path writes. +pub async fn list_pending_payments( + State(state): State, +) -> Result>, (StatusCode, String)> { + let Some(ledger) = &state.payment_ledger else { + return Err(( + StatusCode::SERVICE_UNAVAILABLE, + "no payment rail is wired".to_string(), + )); + }; + Ok(Json(ledger.pending())) +} + +/// POST /api/payments/reconcile (shell-only) — resolve one INDETERMINATE payment against the +/// rail's verdict. This is the ONLY path that releases an indeterminate reservation, and it is +/// deliberately manual-first: the operator asserts what the RAIL says (looked up by idempotency +/// key), never a guess. +/// +/// Ordering, fail-closed against double-refund: +/// 1. The ledger entry resolves EXACTLY once (durable-before-visible with rollback) — a second +/// call, a retry, or a race gets 409 and can never refund twice. Errors are STRUCTURED +/// (council S30 G-F2) so automation never mistakes a retryable failure for a terminal one: +/// 404 = no entry; 409 = already terminal; 503 = the resolution could not persist and the +/// entry is STILL PENDING — retry. +/// 2. Only then, and only for `charged=false`, the reservation is refunded via `try_refund` — +/// "refunded" is claimed ONLY when durably in force; a refund persist failure is surfaced in +/// `warning` (the entry stays resolved: the cap remains debited, recover by raising the limit). +/// An applied refund is marked on the ledger entry (`refund_applied`). +/// 3. The resolution is attested on the signed chain (`Custom` payment_reconciled event) with the +/// ACTUAL outcomes; an attestation failure is surfaced in `warning`, never hidden (the ledger +/// and meter are already consistent — un-resolving would reopen the double-refund window). +/// +/// CRASH WINDOW, stated (council S30 G-F3): a crash between step 1 and step 2 leaves the entry +/// terminally `ResolvedNotCharged` with the refund never applied and no chain event — fail-closed +/// (the cap stays debited; exactly-once holds). FORENSIC: a `resolved_not_charged` ledger entry +/// with `refund_applied=false` and no matching `payment_reconciled` chain event means the refund +/// was lost; the recovery lever is raising the limit. +pub async fn reconcile_payment( + State(state): State, + Json(input): Json, +) -> Result, (StatusCode, String)> { + let (Some(ledger), Some(meter)) = (&state.payment_ledger, &state.spend_meter) else { + return Err(( + StatusCode::SERVICE_UNAVAILABLE, + "no payment rail is wired".to_string(), + )); + }; + reconcile_payment_core(ledger, meter, state.capability_manager.audit_log(), input).map(Json) +} + +/// The ONE shared reconciliation path (Sprint 31): both surfaces (API shell route, gateway +/// Mandates-app route) delegate here so the exactly-once resolve, honest refund claim, structured +/// error mapping, and chain attestation can never drift. +pub(crate) fn reconcile_payment_core( + ledger: &crate::payment_ledger::PaymentLedger, + meter: &elastos_runtime::primitives::spend::SpendMeter, + audit_log: &elastos_runtime::primitives::audit::AuditLog, + input: ReconcilePaymentInput, +) -> Result { + // Council S31 G-F5: a not-charged resolution's REFUND cannot apply while the meter is + // poisoned — and the resolve is one-shot, so proceeding would burn the refund handle + // permanently. Refuse BEFORE touching the ledger (503: retryable after restart). A + // charged=true verdict touches no meter and stays allowed. + if !input.charged && meter.is_poisoned() { + return Err(( + StatusCode::SERVICE_UNAVAILABLE, + "the spend meter is poisoned — a not-charged resolution's refund cannot apply; \ + restart the runtime, then reconcile (resolving now would permanently burn the \ + one-shot refund handle)" + .to_string(), + )); + } + let record = ledger + .resolve(&input.idempotency_key, input.charged) + .map_err(|e| { + let status = match e { + crate::payment_ledger::ResolveError::NotFound => StatusCode::NOT_FOUND, + crate::payment_ledger::ResolveError::NotPending(_) => StatusCode::CONFLICT, + // The obligation is STILL LIVE — automation must retry, never drop the work item. + crate::payment_ledger::ResolveError::Persist + | crate::payment_ledger::ResolveError::Lock => StatusCode::SERVICE_UNAVAILABLE, + }; + (status, format!("cannot reconcile: {e}")) + })?; + let mut warning = None; + let refunded = if input.charged { + false + } else { + match meter.try_refund(&record.capsule, record.amount) { + Ok(_) => { + ledger.mark_refund_applied(&record.idempotency_key); + true + } + Err(e) => { + warning = Some(format!( + "resolution recorded but the refund could not be durably applied ({e}) — \ + the cap remains debited; the operator's lever is raising the limit" + )); + false + } + } + }; + let attested = audit_log.emit(elastos_runtime::primitives::audit::AuditEvent::Custom { + event_type: "payment_reconciled".to_string(), + details: serde_json::json!({ + "idempotency_key": record.idempotency_key, + "capsule": record.capsule, + "payee": record.payee, + "amount": record.amount, + "charged": input.charged, + "refunded": refunded, + }), + }); + if let Err(e) = attested { + tracing::error!( + key = %record.idempotency_key, + "payment reconciliation could not be attested on the audit chain: {e}" + ); + let note = format!( + "reconciliation applied but NOT attested on the audit chain ({e}) — the ledger and \ + meter are consistent; the chain record is missing" + ); + warning = Some(match warning { + Some(w) => format!("{w}; {note}"), + None => note, + }); + } + Ok(ReconcilePaymentOutput { + idempotency_key: record.idempotency_key, + capsule: record.capsule, + amount: record.amount, + status: format!("{:?}", record.status), + refunded, + warning, + }) +} + +/// The Money panel's one-call read (Sprint 31): every provisioned budget (with pending +/// visibility) + the reconciliation work list + the poisoned flag — a read-only projection of the +/// enforcing meter and ledger, shared by both surfaces. +#[derive(Debug, Serialize)] +pub struct MoneyOverview { + pub budgets: Vec, + pub pending: Vec, + pub poisoned: bool, +} + +pub(crate) fn money_overview( + meter: &elastos_runtime::primitives::spend::SpendMeter, + ledger: &crate::payment_ledger::PaymentLedger, +) -> MoneyOverview { + let poisoned = meter.is_poisoned(); + let budgets = meter + .snapshot_all() + .into_iter() + .map(|(capsule, snap)| { + let (pending_units, pending_count) = ledger.pending_for(&capsule); + SpendBudgetOutput { + capsule, + limit: snap.limit, + spent: snap.spent, + remaining: snap.remaining, + poisoned, + pending_units, + pending_count: pending_count as u64, + } + }) + .collect(); + MoneyOverview { + budgets, + pending: ledger.pending(), + poisoned, + } +} + #[derive(Debug, Serialize)] pub struct PreviewStandingGrantOutput { /// "allowed" | "denied" — whether the declared intent WOULD pass its standing grant. @@ -1186,33 +1869,640 @@ pub async fn preview_standing_grant( Ok(Json(out)) } -#[cfg(test)] -mod tests { - use super::*; - use serde_json::json; +/// One mandate as the operator surface renders it — the "mandate card" data shape. +#[derive(Debug, Serialize)] +pub struct MandateCard { + /// The mandate's token id (keys the receipt + revoke). + pub token_id: String, + /// The acting capsule identity the mandate authorizes. + pub capsule: String, + /// Resource scope. + pub resource: String, + /// Action scope. + pub action: String, + /// Affordance methods the agent may invoke. + pub methods: Vec, + /// Expiry (None = until revoked). + pub expires_at: Option, + /// Explicitly revoked? + pub revoked: bool, + /// Live right now (issued, not revoked, not expired)? + pub active: bool, + /// Is the mandate BOUND to one authorized agent key? `true` ⇒ only intents signed by that key + /// may act (strong attribution). `false` ⇒ capsule-string-only authorization: ANY key acting as + /// the capsule passes (weaker; G-M4). Surfaced so the operator can SEE the attribution strength + /// of every mandate, not just trust it (P12). + pub agent_bound: bool, + /// The authorized agent's ed25519 verifying key (hex), when bound — the operator's own issued + /// key, so exposing it here is not a leak (public key, operator surface). `None` when unbound. + pub agent_pubkey: Option, + /// The dispatch-rate budget ENFORCED for this mandate: acts per `dispatch_window_secs` window. + /// Always the effective number (the mandate's own limit when it set one, else the global + /// default) — the card shows what the gate does, not a config abstraction (P12). + pub dispatch_limit: u32, + /// Whether `dispatch_limit` was set on THIS mandate at grant time (`true`) or is the global + /// default (`false`) — so the operator can tell a deliberate dial from the baseline. + pub dispatch_limit_custom: bool, + /// The rate window (seconds) the budget is measured over. + pub dispatch_window_secs: u64, + /// The RESPONSIBLE ENTITY (Sprint 32): the DID the operator DECLARED accountable — the working + /// registry MIRROR of the signed grant record. `None` = not recorded in the registry (a pre-S32 + /// or CLI-minted mandate, OR a hand-edited/repaired snapshot that dropped the unsigned field). + /// AUTHORITATIVE SOURCE IS THE RECEIPT: the signed grant record in `elastos verify-receipt` is + /// the ground truth; this card projection can be blanked/altered by a data_dir writer (the whole + /// registry snapshot is unsigned) without touching the receipt (council S32 F3/F4). + pub responsible_entity: Option, +} - #[test] - fn test_supported_resource_schemes() { - assert!(is_supported_resource_scheme("elastos://did/*")); - assert!(is_supported_resource_scheme("elastos://ai/local/chat")); - assert!(is_supported_resource_scheme( - "localhost://MyWebSite/Documents/*" - )); - } +#[derive(Debug, Serialize)] +pub struct ListMandatesOutput { + /// Every standing mandate issued this runtime lifetime, revoked ones included (an operator + /// surface shows what was killed, it does not erase it), sorted by token id. + pub mandates: Vec, + /// The runtime audit chain's signer key (hex) — the pin the operator passes to + /// `elastos verify-receipt --signer`. `None` for an unsigned/memory-only log. Honest bounds: + /// this key rides the loopback control plane, whose trust root is the operator's 0600 + /// coords/attach-secret files — the attach exchange authenticates the CLIENT to the runtime; + /// runtime identity rests on that filesystem + loopback assumption, not on a cryptographic + /// server credential. It breaks receipt-SELF-pinning; it is not third-party attestation. + pub signer_public_key_hex: Option, +} - #[test] - fn test_rejects_unsupported_resource_schemes() { - assert!(!is_supported_resource_scheme("elastos:/broken")); - assert!(!is_supported_resource_scheme("localhost:/broken")); - assert!(!is_supported_resource_scheme("resource-without-scheme")); - assert!(!is_supported_resource_scheme("")); +/// Build the operator's mandate list — the ONE source of truth for the "mandate card" projection, +/// shared by the API server's [`list_standing_grants`] and the gateway's read-only mandates app +/// (`api::gateway::gateway_mandates`), so the liveness invariant can never drift between the two +/// surfaces (a revoked/expired mandate rendering "Live" on one but not the other). +/// +/// The card's LIVE bit must consult ALL kill paths, because the envelope's own `revoked` flag sees +/// only standing/`revoke_all` revocation — a backing token can also die by (a) an individual token +/// revoke through the manager's revocation store, or (b) a key-rotation EPOCH advance (captured in +/// the envelope at issue). A mandate killed by any of these must never render live. An unparseable +/// id is fail-closed inactive. +pub async fn mandate_cards( + standing_service: &StandingGrantService, + capability_manager: &CapabilityManager, +) -> ListMandatesOutput { + let mut mandates = Vec::new(); + for env in standing_service.list() { + let token_dead = match TokenId::from_hex(&env.grant_id) { + Ok(id) => { + capability_manager.is_token_revoked(&id).await + || !capability_manager.is_epoch_valid(env.token_epoch) + } + Err(_) => true, + }; + mandates.push(MandateCard { + active: env.is_active() && !token_dead, + token_id: env.grant_id, + capsule: env.capsule, + resource: env.resource, + action: env.action, + methods: env.allowed_methods.into_iter().collect(), + expires_at: env.expires_at, + revoked: env.revoked || token_dead, + agent_bound: env.agent_pubkey.is_some(), + agent_pubkey: env.agent_pubkey, + dispatch_limit: env + .dispatch_limit + .unwrap_or(elastos_runtime::capability::MANDATE_DISPATCH_LIMIT), + dispatch_limit_custom: env.dispatch_limit.is_some(), + dispatch_window_secs: elastos_runtime::capability::MANDATE_DISPATCH_WINDOW_SECS, + responsible_entity: env.responsible_entity, + }); + } + ListMandatesOutput { + mandates, + signer_public_key_hex: capability_manager.audit_log().verifying_key_hex(), } +} - #[test] - fn test_system_only_backend_resource_detection() { - assert!(is_system_only_backend_resource("elastos://ipfs/add")); - assert!(is_system_only_backend_resource("elastos://ipfs")); - assert!(is_system_only_backend_resource("elastos://kubo/rpc")); +/// GET /api/standing-grants (shell-only) — the operator's mandate list. +pub async fn list_standing_grants( + State(state): State, +) -> Json { + Json(mandate_cards(&state.standing_service, &state.capability_manager).await) +} + +#[derive(Debug, Serialize)] +pub struct DispatchIntentOutput { + /// The outcome, reflecting the gate AND the reconciliation: + /// - `denied` — the intent fell outside a live mandate (see `reason`); nothing performed. + /// - `performed` — authorized AND a real executor performed it as declared (`Matched`). + /// - `diverged` — authorized, but the executor did something other than declared (`Diverged`). + /// - `authorized_not_performed` — authorized, but NO RECEIPT ATTESTS performance + /// (`Undelivered`). This is absence-of-attestation, not proof-of-absence: for a MONEY act + /// the effect may still have occurred (an INDETERMINATE rail outcome — timeout/5xx/panic — + /// deliberately reconciles here; council S29 F5). Check `reason` before treating it as + /// "nothing happened". + /// + /// Only `performed` records a successful `CapabilityUse` in the mandate receipt. + pub outcome: String, + /// The fail-closed denial reason (snake_case) when `denied`; for an authorized-but-declined + /// act, the EXECUTOR's decline reason (S29 F2) — for money acts this distinguishes a + /// cap-refusal from an INDETERMINATE outcome and names the idempotency key to reconcile with + /// the rail. `None` when performed. + pub reason: Option, + /// The signed reconciliation when the intent was authorized (any of performed/diverged/ + /// authorized_not_performed); `None` when denied. Its `status` is the independent verdict of + /// what the executor actually did vs. what was declared. + pub reconciliation: Option, + /// Data the EXECUTOR explicitly disclosed to the agent (Sprint 39): `runtime.market_quote` + /// returns the quoted terms here (`price=…;tok=…;supply=…`). Absent for every other + /// affordance BY DESIGN — disclosure is per-executor opt-in, so `state_get`'s one-bit + /// discipline cannot be eroded by the pipeline. + #[serde(skip_serializing_if = "Option::is_none")] + pub report: Option, +} + +/// POST /api/agent/dispatch (AGENT-FACING — Sprint 26) — the same ACT leg, but reachable by the +/// AGENT itself, not only the operator/shell. This is the North-Star move: "a mandate, not your +/// keys". The route carries NO consent-broker (shell-role) gate; the agent authenticates AS the +/// mandate holder — `verify_self` proves it holds a private key, and the mandate's agent-key binding +/// (G-M4) proves that key is the authorized agent. No ambient authority (P3): an UNBOUND mandate is +/// REFUSED here (only the operator's shell route may dispatch an unbound mandate), and a wrong-key +/// intent is refused BEFORE any rate budget is charged or durable write is made — CHARGE-ON-AUTHORIZED, +/// which closes the Sprint 21 victim-lockout residual (an attacker naming a victim's grant can no +/// longer burn its budget, because it never clears this gate). The response is a uniform 403 for +/// absent / unbound / wrong-key, so this less-trusted surface is not a grant-existence or binding +/// oracle. Everything past the gate is the identical hardened pipeline (freshness → per-mandate rate +/// → replay guard → liveness → gate → act → reconcile → receipt); the gate RE-checks the binding, so +/// this wrapper only ADDS the agent authentication + the charge-on-authorized ordering. +pub async fn dispatch_agent_intent( + State(state): State, + Json(intent): Json, +) -> Result, (StatusCode, String)> { + // 1. The intent must be validly self-signed before we trust `intent.signer`. + if !intent.verify_self() { + return Err(( + StatusCode::BAD_REQUEST, + "intent declaration signature did not verify".to_string(), + )); + } + // 2. Authenticate as the mandate holder: the named mandate must EXIST, be agent-BOUND, and its + // bound key must be the intent's signer. Absent / unbound / wrong-key all fail-closed the + // SAME way (no oracle). This runs BEFORE delegating, so the pipeline's rate budget + durable + // replay write are only ever reached by an authorized caller (charge-on-authorized). + let authorized = TokenId::from_hex(intent.standing_grant_id.trim()) + .ok() + .and_then(|t| state.standing_service.get(&t.to_string())) + .and_then(|grant| grant.agent_pubkey) + .map(|bound| intent.signer.trim().eq_ignore_ascii_case(bound.trim())) + .unwrap_or(false); + if !authorized { + return Err(( + StatusCode::FORBIDDEN, + "not authorized: agent dispatch requires an intent signed by the key your mandate is \ + bound to (unbound mandates are dispatched only from the operator shell)" + .to_string(), + )); + } + // 3. Delegate to the ONE hardened pipeline — the single source of truth (it re-verifies the + // signature and re-checks the binding in the gate). This wrapper adds only the agent auth. + dispatch_standing_intent(State(state), Json(intent)).await +} + +/// POST /api/standing-grants/dispatch (shell-only) — the ACT leg of the mandate loop. +/// +/// Run ONE agent act under its standing mandate, fail-closed. In order: +/// 1. authenticate the signed [`IntentDeclarationV1`] (`verify_self`) — a forged declaration is +/// rejected before any lookup or record; +/// 2. REPLAY GUARD (G-M5): each `intent_id` acts at most once per runtime lifetime — a re-POSTed +/// signed blob is refused `409`, so a captured/retried declaration cannot double-act; +/// 3. LIVENESS (G-M1): consult the manager's token-revocation store AND epoch validity (the pure +/// envelope gate can see neither) — if the backing token is dead by ANY path (individual +/// revoke, `revoke_all`, or a key-rotation epoch advance) the envelope is healed to revoked so +/// the gate denies with the true `revoked` reason; +/// 4. run the intent gate: the declaration is recorded on-chain BEFORE the act (no custody ⇒ no +/// act), and the gate binds capsule + BOUND AGENT KEY (G-M4, when the mandate set one) + method +/// + resource + action, all exact; +/// 5. run the intent gate: ONLY on authorization does the act closure invoke the real +/// [`IntentExecutor`](crate::intent_executor::IntentExecutor) — so a denied/revoked intent never +/// executes — and the receipt is minted from what the executor REPORTS it performed (G-M6); +/// 6. record a token-keyed `CapabilityUse` (G-M2) whose `success` reflects the reconciliation +/// STATUS (a real `matched` performance), so the mandate's exported receipt carries the act. +/// +/// Honest scope: reconciliation attests report-fidelity (report == declaration), not reality +/// (effect == declaration) — that rests on the trusted-core executor's truthfulness. The production +/// executor set currently registers ONE real affordance (`runtime.audit_verify`, a side-effect-free +/// signature-verified chain read); every other method is `authorized_not_performed` until wired (G-M6). +pub async fn dispatch_standing_intent( + State(state): State, + Json(intent): Json, +) -> Result, (StatusCode, String)> { + if !intent.verify_self() { + return Err(( + StatusCode::BAD_REQUEST, + "intent declaration signature did not verify".to_string(), + )); + } + // FRESHNESS WINDOW (G-M7): a signed declaration EXPIRES — its `declared_at` must sit within + // `[now - MAX_INTENT_AGE, now + MAX_CLOCK_SKEW]`. This bounds how long a captured intent can be + // replayed AND lets the replay guard forget anything older than the window (so its seen-set is + // bounded, not monotonic). Checked AFTER authenticity (a forged declaration is rejected first) + // and BEFORE the replay guard registers the id, so a stale/future intent never burns an id. + let now_secs = elastos_common::SecureTimestamp::now().unix_secs; + if let Err(reason) = + elastos_runtime::capability::check_intent_freshness(intent.declared_at.unix_secs, now_secs) + { + return Err(( + StatusCode::BAD_REQUEST, + format!( + "intent declaration outside the freshness window: {}", + reason.as_str() + ), + )); + } + // GRANT EXISTENCE (G-M7, Sprint 21 council fix): the intent names a standing grant. Resolve it + // in memory HERE — after authenticity + freshness, but BEFORE the rate budget AND the durable + // replay write. An unparseable or UNKNOWN grant_id is refused cheaply now, so a flood of + // distinct FAKE grant_ids (each self-signed + fresh; `standing_grant_id` is attacker-chosen and + // is only bound to a real mandate LATER, at the gate) can neither (a) reach the durable + // replay-guard fsync nor (b) create a rate-map entry. This is what actually makes the rate + // budget bound the fsync flood and keeps the rate map bounded: only REAL, operator-issued + // grant_ids — a registry-bounded set — are ever counted or durably recorded. A never-issued + // grant yields the SAME `denied`/`no_standing_grant` verdict the gate would, without paying for + // it. (Real-but-revoked grants stay in the registry, so they pass here and are denied with the + // true `revoked` reason downstream.) + let grant_exists = TokenId::from_hex(intent.standing_grant_id.trim()) + .ok() + .map(|t| state.standing_service.get(&t.to_string()).is_some()) + .unwrap_or(false); + if !grant_exists { + return Ok(Json(DispatchIntentOutput { + outcome: "denied".to_string(), + reason: Some( + elastos_runtime::capability::EnvelopeDenial::NoGrant + .as_str() + .to_string(), + ), + reconciliation: None, + report: None, + })); + } + // RATE BUDGET (G-M7): each mandate may perform at most MANDATE_DISPATCH_LIMIT acts per window. + // Checked AFTER authenticity + freshness + grant-existence (only well-formed fresh intents + // naming a REAL mandate count) and BEFORE the replay guard's durable write, so a mandate-holding + // agent flooding distinct intents is refused (429) before it costs an fsync + registry growth — + // bounding the durable-write flood the replay guard's compaction alone did not (Sprint 19 + // bounded the SET; this bounds the RATE). + if !state + .standing_service + .record_dispatch_within_budget(&intent.standing_grant_id, now_secs) + { + // Report THIS mandate's resolved budget, not the global default (council F1, P12): a + // mandate dialed to 2/min must not be told it exceeded "60 acts" — the message would + // contradict the gate. Re-resolve the enforced limit from the registry for the message. + return Err(( + StatusCode::TOO_MANY_REQUESTS, + format!( + "mandate {} exceeded its dispatch rate budget ({} acts per {}s)", + intent.standing_grant_id, + state + .standing_service + .dispatch_limit_for(&intent.standing_grant_id), + elastos_runtime::capability::MANDATE_DISPATCH_WINDOW_SECS + ), + )); + } + // Replay guard (G-M5): register the intent id BEFORE anything acts — durably, so the guard + // survives restart. A duplicate is refused with no record and no act. Register only AFTER + // authenticity + freshness (above) so a forged or stale blob cannot burn a future-legitimate + // id. A guard that cannot be durably recorded REFUSES the act (fail-closed) with its true + // reason — an intent that acts without a surviving replay record could act again after a reboot. + match state.standing_service.record_fresh_intent( + &intent.intent_id, + intent.declared_at.unix_secs, + now_secs, + ) { + Ok(true) => {} + Ok(false) => { + return Err(( + StatusCode::CONFLICT, + // "consumed", not "dispatched" (guardian F5): the id burns when REGISTERED — a + // prior attempt may have been refused after registration and never acted. + format!( + "intent {} was already consumed (replay refused)", + intent.intent_id + ), + )); + } + Err(e) => { + return Err(( + StatusCode::INTERNAL_SERVER_ERROR, + format!("replay guard could not be durably recorded — intent refused: {e}"), + )); + } + } + // ONE action parser (`parse_action` → `Action`'s `FromStr`), so the gate's accepted set can + // never drift from the enum variants (council S50 guardian F4). + let action = parse_action(&intent.action)?; + // Liveness (G-M1): the envelope gate sees only its own `revoked` flag. A backing token can die + // by three other paths the gate cannot see — individual revoke, `revoke_all`, and a key-rotation + // epoch advance. Consult BOTH the revocation store and epoch validity (using the epoch captured + // in the envelope at issue), and heal the envelope to revoked so the gate denies with the true + // `revoked` reason and it sticks. Unparseable ids fail closed at the gate (NoGrant). + if let Ok(token_id) = TokenId::from_hex(intent.standing_grant_id.trim()) { + let revoked = state.capability_manager.is_token_revoked(&token_id).await; + let epoch_dead = state + .standing_service + .get(&token_id.to_string()) + .map(|env| !state.capability_manager.is_epoch_valid(env.token_epoch)) + .unwrap_or(false); + if revoked || epoch_dead { + // The heal must STICK before dispatch proceeds: if the registry cannot record the + // envelope revoke, refuse the intent rather than let the gate read a live envelope + // whose backing token is dead. (The gate itself would still deny via the token check, + // but a fail-open heal here would leave disk claiming LIVE across a restart.) + if let Err(e) = state.standing_service.revoke(&token_id.to_string()) { + return Err(( + StatusCode::INTERNAL_SERVER_ERROR, + format!( + "mandate is token-dead but the registry could not record the envelope \ + revoke — intent refused: {e}" + ), + )); + } + } + } + let manager = state.capability_manager.clone(); + let executor = state.intent_executor.clone(); + let token_str = intent.standing_grant_id.clone(); + let intent_for_exec = intent.clone(); + // If the executor PERFORMS but reports an action the runtime cannot represent, we must NOT + // silently record "authorized_not_performed" (that would HIDE a real effect); surface it. + let unrepresentable = Arc::new(std::sync::atomic::AtomicBool::new(false)); + let unrepresentable_w = unrepresentable.clone(); + // The executor's DECLINE reason must reach the caller (council S29 F2): for a money act an + // INDETERMINATE outcome ("the charge may have posted; reconcile under this idempotency key") + // and a plain cap-refusal are indistinguishable without it — and the reason is the ONLY + // artifact naming the reconciliation key. Captured here, surfaced in the response `reason` + // and error-logged; putting it on-chain stays the tracked follow-on (S27 F3). + let decline_reason = Arc::new(std::sync::Mutex::new(None::)); + let decline_reason_w = decline_reason.clone(); + // The rail reference of a PERFORMED rail act (Sprint 34): captured out of the executor + // closure the same way as the decline reason, so the out-of-closure `CapabilityUse` emit can + // bind it onto the signed record (and thus the portable receipt). `None` for every non-rail + // act; only a `Matched` performance carries it onto the chain (see the emit below). + let rail_ref_slot = Arc::new(std::sync::Mutex::new(None::)); + let rail_ref_w = rail_ref_slot.clone(); + // Sprint 39: the executor's EXPLICIT agent disclosure (market_quote's terms) — same + // side-channel pattern as rail_ref; only what an executor opts in ever reaches the response. + let report_slot = Arc::new(std::sync::Mutex::new(None::)); + let report_w = report_slot.clone(); + // The act runs ONLY when the gate authorizes (dispatch calls this closure solely on the Acted + // path), so a denied/revoked/wrong-agent intent never invokes the executor — "no authorization + // ⇒ no act". The receipt is minted from what the executor REPORTS it performed, never from the + // declaration, so reconcile compares performed-vs-declared honestly. + // spawn_blocking (council S29 G-F8/RT-F2 residual): the executor can block for up to the + // rail's timeout (the pay path joins its rail thread), and the gate itself does durable + // fsync work — neither belongs on an async worker. The whole authorize→act→reconcile + // pipeline runs on the blocking pool; the in-flight payment bound caps how many of these + // can hold blocking threads at once. + // The ENTIRE gate→act→reconcile→use-record pipeline lives inside ONE blocking task (council + // S30 G-F6): a client disconnect cancels only the awaiting future, never the started blocking + // task, so a performed act can no longer lose its G-M2 CapabilityUse projection to a + // cancellation between the act and the record. + let dispatch_service = state.standing_service.clone(); + let manager_for_use = state.capability_manager.clone(); + let intent_for_gate = intent.clone(); + let out = tokio::task::spawn_blocking(move || { + let outcome = dispatch_service.dispatch(&intent_for_gate, move || { + match executor.execute(&intent_for_exec) { + crate::intent_executor::IntentExecution::Declined { reason } => { + if reason.contains("INDETERMINATE") { + tracing::error!( + capsule = %intent_for_exec.capsule, + "indeterminate money outcome on dispatch: {reason}" + ); + } + if let Ok(mut slot) = decline_reason_w.lock() { + *slot = Some(reason); + } + None + } + crate::intent_executor::IntentExecution::Performed { + capsule, + method_id, + input_hash, + resource, + action: performed_action, + rail_ref, + agent_visible_report, + } => { + // Stash the rail reference for the out-of-closure use-record. Set only when the + // executor actually settled on a rail (a DRM/pay act); the emit binds it onto the + // chain ONLY on a Matched reconciliation. + if let Some(rail_ref) = rail_ref { + if let Ok(mut slot) = rail_ref_w.lock() { + *slot = Some(rail_ref); + } + } + // Stash the executor's EXPLICIT agent disclosure (Sprint 39 — market_quote's + // terms). Only what the executor opted in reaches the response; the pipeline + // never surfaces receipt echoes wholesale (state_get's one-bit rule stays + // structural). + if let Some(report) = agent_visible_report { + if let Ok(mut slot) = report_w.lock() { + *slot = Some(report); + } + } + let performed = match performed_action.to_lowercase().as_str() { + "read" => Action::Read, + "write" => Action::Write, + "execute" => Action::Execute, + "delete" => Action::Delete, + "message" => Action::Message, + "admin" => Action::Admin, + _ => { + unrepresentable_w.store(true, std::sync::atomic::Ordering::SeqCst); + return None; + } + }; + Some(manager.issue_affordance_receipt( + &token_str, + &capsule, + &method_id, + &input_hash, + &resource, + performed, + )) + } + } + }); + if unrepresentable.load(std::sync::atomic::Ordering::SeqCst) { + return Err(( + StatusCode::INTERNAL_SERVER_ERROR, + "executor reported an unrepresentable action; the act may have occurred but \ + could not be reconciled — refusing to record it as either performed or \ + not-performed" + .to_string(), + )); + } + use elastos_runtime::capability::{IntentGateOutcome, ReconciliationStatus}; + let (out, acted) = match outcome { + IntentGateOutcome::BlockedNoCustody(e) => { + // Custody is mandatory: the declaration could not land on the chain, so nothing + // ran and nothing further is recordable — surface it, emit nothing else. + return Err(( + StatusCode::INTERNAL_SERVER_ERROR, + format!("intent custody write failed; act not run: {e}"), + )); + } + IntentGateOutcome::Denied(reason) => ( + DispatchIntentOutput { + outcome: "denied".to_string(), + reason: Some(reason.as_str().to_string()), + reconciliation: None, + report: None, + }, + false, + ), + IntentGateOutcome::Acted(rec) => { + // The intent was AUTHORIZED (passed the gate); the reconciliation says whether it + // was actually PERFORMED. `success` (and the receipt's use) is true ONLY for a + // `Matched` performance — a `Diverged` act (executor did something else) or + // `Undelivered` one (nothing performed it) records success=false and says so + // honestly in the outcome. + let (label, matched) = match rec.status { + ReconciliationStatus::Matched => ("performed", true), + ReconciliationStatus::Diverged => ("diverged", false), + ReconciliationStatus::Undelivered => ("authorized_not_performed", false), + }; + ( + DispatchIntentOutput { + outcome: label.to_string(), + // The executor's decline reason (S29 F2): distinguishes a cap-refusal + // from an INDETERMINATE money outcome, and carries the idempotency key + // the operator reconciles with. `None` for a performed act or a + // non-executor decline. + reason: decline_reason.lock().ok().and_then(|mut s| s.take()), + reconciliation: Some(rec), + // The explicit disclosure, surfaced only when the act genuinely + // PERFORMED as declared — a diverged/undelivered act discloses nothing. + // Defense-in-depth at the boundary (mirrors rail_ref's emit-site + // re-sanitization): bound + printable-filter for ANY future executor, + // not just today's terms-shaped producer. + report: if matched { + report_slot.lock().ok().and_then(|mut s| s.take()).map(|r| { + r.chars() + .filter(|c| c.is_ascii_graphic() || *c == ' ') + .take(256) + .collect() + }) + } else { + None + }, + }, + matched, + ) + } + }; + // G-M2: token-keyed projection of the outcome, so export_mandate_receipt_for_capability + // carries the intent-channel act (or its denial) in the mandate's receipt. Best-effort + // (like the validate-path use records): a lost emit under-reports in the receipt but the + // intent-keyed declaration + reconciliation are already durably on the chain. + if let Ok(token_id) = TokenId::from_hex(intent_for_gate.standing_grant_id.trim()) { + // Sprint 34: bind the rail reference onto the signed use record — but ONLY on a + // Matched performance (`acted`). A diverged/undelivered act records success=false and + // carries no rail_ref: a receipt row that names a settlement tx must correspond to a + // reconciled act, never an unperformed or divergent one. + let rail_ref = if acted { + rail_ref_slot.lock().ok().and_then(|mut s| s.take()) + } else { + None + }; + // Defense in depth at the SIGNING boundary (council S34 guardian F6): the pay closure + // already sanitizes, but re-sanitize here so the signed-field invariant (printable, + // bounded) is local to the emit site and holds for ANY future executor that sets + // Performed.rail_ref. Idempotent on an already-clean reference; empty ⇒ omitted. + let rail_ref = rail_ref + .map(|r| crate::payment_ledger::sanitize_rail_note(&r)) + .filter(|r| !r.is_empty()); + manager_for_use.audit_log().capability_use_with_rail_ref( + &token_id, + &intent_for_gate.capsule, + &ResourceId::new(intent_for_gate.resource.clone()), + action, + acted, + rail_ref, + ); + } + Ok(out) + }) + .await + .map_err(|e| { + // JoinError = the blocking task PANICKED (blocking tasks are never cancelled once + // started). Honest bound (council S30 G-F5): the panic may have struck AFTER the act — + // the act may have been performed and not reported here. The declaration (and, if it + // ran, the reconciliation) is on the chain; a money act is in the payment ledger; a + // retry of the same intent is refused by the replay guard. + ( + StatusCode::INTERNAL_SERVER_ERROR, + format!( + "dispatch task panicked — the act may have been performed and not reported; \ + consult the audit chain and payment ledger before acting ({e})" + ), + ) + })??; + Ok(Json(out)) +} + +/// GET /api/mandate/:token_id/receipt (shell-only) +/// +/// Export the PORTABLE per-mandate receipt for one capability token: the signed, set-bound bundle +/// of its grant + every use/revoke, straight from the runtime's durable audit chain — the artifact +/// an operator hands an auditor, verified off-box with `elastos verify-receipt`. Read-only over +/// the chain; mints nothing, mutates nothing. `404` when the token has no durable records (unknown +/// id, or a memory-only/unsigned log — absence is reported, never fabricated). +pub async fn mandate_receipt( + State(state): State, + Path(token_id): Path, // Shell check done by middleware +) -> Result, (StatusCode, String)> { + // Canonicalize: only a well-formed token id can key a mandate (and its Display form is the + // exact string the audit records carry). + let token_id = TokenId::from_hex(token_id.trim()) + .map_err(|e| (StatusCode::BAD_REQUEST, format!("invalid token id: {e}")))? + .to_string(); + let receipt = state + .capability_manager + .audit_log() + .export_mandate_receipt_for_capability(&token_id) + .ok_or_else(|| { + ( + StatusCode::NOT_FOUND, + format!("no durable audit records for mandate {token_id}"), + ) + })?; + Ok(Json(receipt)) +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + #[test] + fn test_supported_resource_schemes() { + assert!(is_supported_resource_scheme("elastos://did/*")); + assert!(is_supported_resource_scheme("elastos://ai/local/chat")); + assert!(is_supported_resource_scheme( + "localhost://MyWebSite/Documents/*" + )); + } + + #[test] + fn test_rejects_unsupported_resource_schemes() { + assert!(!is_supported_resource_scheme("elastos:/broken")); + assert!(!is_supported_resource_scheme("localhost:/broken")); + assert!(!is_supported_resource_scheme("resource-without-scheme")); + assert!(!is_supported_resource_scheme("")); + } + + #[test] + fn test_system_only_backend_resource_detection() { + assert!(is_system_only_backend_resource("elastos://ipfs/add")); + assert!(is_system_only_backend_resource("elastos://ipfs")); + assert!(is_system_only_backend_resource("elastos://kubo/rpc")); assert!(is_system_only_backend_resource( "elastos://ipfs-cluster/pins" )); @@ -1229,65 +2519,3622 @@ mod tests { )); } - fn assert_rejects_unknown_field(value: serde_json::Value) { - let err = match serde_json::from_value::(value) { - Ok(_) => panic!("expected capability body to reject unknown fields"), - Err(err) => err.to_string(), + fn assert_rejects_unknown_field(value: serde_json::Value) { + let err = match serde_json::from_value::(value) { + Ok(_) => panic!("expected capability body to reject unknown fields"), + Err(err) => err.to_string(), + }; + assert!(err.contains("unknown field"), "{err}"); + } + + #[test] + fn test_capability_inputs_reject_hidden_authority_fields() { + assert_rejects_unknown_field::(json!({ + "resource": "elastos://content/publish", + "action": "write", + "capability_token": "must-not-be-accepted" + })); + assert_rejects_unknown_field::(json!({ + "request_id": "request:test", + "duration": "session", + "rationale": "ok", + "token": "must-not-be-accepted" + })); + assert_rejects_unknown_field::(json!({ + "request_id": "request:test", + "reason": "no", + "override": true + })); + assert_rejects_unknown_field::(json!({ + "reason": "rotate", + "session_id": "session:other" + })); + assert_rejects_unknown_field::(json!({ + "limit": 10, + "type": "capability_grant", + "include_private": true + })); + } + + fn test_state() -> CapabilityState { + let audit_log = std::sync::Arc::new(elastos_runtime::primitives::audit::AuditLog::new()); + let store = std::sync::Arc::new(elastos_runtime::capability::CapabilityStore::new()); + let metrics = + std::sync::Arc::new(elastos_runtime::primitives::metrics::MetricsManager::new()); + let capability_manager = + std::sync::Arc::new(CapabilityManager::new(store, audit_log.clone(), metrics)); + let standing_service = std::sync::Arc::new(capability_manager.standing_grant_service()); + let intent_executor = std::sync::Arc::new( + crate::intent_executor::MethodRegistryExecutor::production(audit_log.clone(), None), + ); + + CapabilityState { + pending_store: std::sync::Arc::new(PendingRequestStore::new(audit_log.clone())), + capability_manager, + policy_evaluator: std::sync::Arc::new(PolicyEvaluator::new( + Box::new(elastos_runtime::capability::evaluator::ShellPassthroughVerifier), + audit_log, + )), + standing_service, + intent_executor, + spend_meter: None, + payment_ledger: None, + } + } + + /// G-M4 (Sprint 20): the mandate card SURFACES binding honestly (P12), and the API/CLI path + /// STILL allows an UNBOUND mandate for the trusted operator (G-M3) — only the web surface + /// requires binding. A bound mandate's card carries `agent_bound=true` + the key; an unbound + /// one carries `agent_bound=false`. + #[tokio::test] + async fn card_surfaces_agent_binding_and_api_still_allows_unbound() { + let state = test_state(); + let agent = hex::encode( + ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()) + .verifying_key() + .to_bytes(), + ); + // BOUND via the API — allowed, card shows it. + let bound = issue_standing_grant( + State(state.clone()), + Json(IssueStandingGrantInput { + capsule: "vm-agent".to_string(), + resource: "elastos://mail/send".to_string(), + action: "execute".to_string(), + methods: vec!["send".to_string()], + ttl_secs: Some(3600), + agent_pubkey: Some(agent.clone()), + dispatch_limit: None, + responsible_entity: None, + }), + ) + .await + .expect("bound issue ok") + .0; + // UNBOUND via the API — STILL allowed (G-M3, the trusted operator/CLI path). + let unbound = issue_standing_grant( + State(state.clone()), + Json(IssueStandingGrantInput { + capsule: "vm-agent2".to_string(), + resource: "elastos://mail/send".to_string(), + action: "execute".to_string(), + methods: vec!["send".to_string()], + ttl_secs: Some(3600), + agent_pubkey: None, + dispatch_limit: None, + responsible_entity: None, + }), + ) + .await + .expect("unbound issue STILL allowed on the API path (G-M3)") + .0; + + let cards = mandate_cards(&state.standing_service, &state.capability_manager).await; + let bc = cards + .mandates + .iter() + .find(|c| c.token_id == bound.grant_id) + .unwrap(); + assert!(bc.agent_bound, "bound mandate card shows agent_bound"); + assert_eq!(bc.agent_pubkey.as_deref(), Some(agent.as_str())); + let uc = cards + .mandates + .iter() + .find(|c| c.token_id == unbound.grant_id) + .unwrap(); + assert!( + !uc.agent_bound, + "unbound mandate card shows agent_bound=false" + ); + assert!(uc.agent_pubkey.is_none()); + } + + /// Council red-team F1 (Sprint 20): a WEAK (small-order / identity) ed25519 key is refused at + /// issue — it parses as valid 32 bytes but a forged signature validates for it under any + /// message, so a mandate "bound" to it would be forgeable (effectively unbound wearing a bound + /// badge). A real key still binds. + #[tokio::test] + async fn issue_refuses_a_weak_agent_key() { + let state = test_state(); + // The ed25519 identity point and all-zeros are small-order (weak). + for weak in [ + "0100000000000000000000000000000000000000000000000000000000000000", + "0000000000000000000000000000000000000000000000000000000000000000", + ] { + let res = issue_standing_grant( + State(state.clone()), + Json(IssueStandingGrantInput { + capsule: "vm-agent".to_string(), + resource: "elastos://mail/send".to_string(), + action: "execute".to_string(), + methods: vec!["send".to_string()], + ttl_secs: Some(3600), + agent_pubkey: Some(weak.to_string()), + dispatch_limit: None, + responsible_entity: None, + }), + ) + .await; + assert!( + matches!(res, Err((StatusCode::BAD_REQUEST, _))), + "weak key {weak} refused" + ); + } + assert!( + state.standing_service.list().is_empty(), + "no weak-bound mandate was minted" + ); + // A REAL key still binds. + let real = hex::encode( + ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()) + .verifying_key() + .to_bytes(), + ); + assert!(issue_standing_grant( + State(state.clone()), + Json(IssueStandingGrantInput { + capsule: "vm-agent".to_string(), + resource: "elastos://mail/send".to_string(), + action: "execute".to_string(), + methods: vec!["send".to_string()], + ttl_secs: Some(3600), + agent_pubkey: Some(real), + dispatch_limit: None, + responsible_entity: None, + }), + ) + .await + .is_ok()); + } + + #[tokio::test] + async fn issue_then_revoke_standing_grant_over_the_handlers() { + let state = test_state(); + let out = issue_standing_grant( + State(state.clone()), + Json(IssueStandingGrantInput { + capsule: "vm-agent".to_string(), + resource: "elastos://mail/send".to_string(), + action: "execute".to_string(), + methods: vec!["send".to_string()], + ttl_secs: Some(3600), + agent_pubkey: None, + dispatch_limit: None, + responsible_entity: None, + }), + ) + .await + .expect("issue ok") + .0; + assert!(!out.grant_id.is_empty(), "issue returns a grant id"); + assert!( + state.standing_service.is_active(&out.grant_id), + "the issued grant is active in the shared service" + ); + + // Revoke → true; the grant goes inactive; a second revoke → false (idempotent kill switch). + let rev = revoke_standing_grant( + State(state.clone()), + Json(RevokeStandingGrantInput { + grant_id: out.grant_id.clone(), + }), + ) + .await + .expect("revoke ok") + .0; + assert!(rev.revoked, "revoking a live grant returns true"); + assert!(!state.standing_service.is_active(&out.grant_id)); + let rev2 = revoke_standing_grant( + State(state.clone()), + Json(RevokeStandingGrantInput { + grant_id: out.grant_id.clone(), + }), + ) + .await + .expect("ok") + .0; + assert!(!rev2.revoked, "double-revoke returns false"); + } + + /// G-M5 over the REAL handlers: a mandate issued through `issue_standing_grant` is still live + /// after a registry "reboot" (a fresh service over the same snapshot file), and one revoked + /// through `revoke_standing_grant` STAYS dead — never crash-revived. + #[tokio::test] + async fn mandates_survive_restart_over_the_handlers() { + let dir = tempfile::tempdir().unwrap(); + let registry_path = dir.path().join("standing_grants.json"); + let audit_log = std::sync::Arc::new(elastos_runtime::primitives::audit::AuditLog::new()); + let store = std::sync::Arc::new(elastos_runtime::capability::CapabilityStore::new()); + let metrics = + std::sync::Arc::new(elastos_runtime::primitives::metrics::MetricsManager::new()); + let capability_manager = + std::sync::Arc::new(CapabilityManager::new(store, audit_log.clone(), metrics)); + let standing_service = std::sync::Arc::new( + capability_manager + .standing_grant_service_with_persistence(®istry_path) + .unwrap(), + ); + let state = CapabilityState { + pending_store: std::sync::Arc::new(PendingRequestStore::new(audit_log.clone())), + capability_manager: capability_manager.clone(), + policy_evaluator: std::sync::Arc::new(PolicyEvaluator::new( + Box::new(elastos_runtime::capability::evaluator::ShellPassthroughVerifier), + audit_log.clone(), + )), + standing_service, + intent_executor: std::sync::Arc::new( + crate::intent_executor::MethodRegistryExecutor::production(audit_log, None), + ), + spend_meter: None, + payment_ledger: None, + }; + + let out = issue_standing_grant( + State(state.clone()), + Json(IssueStandingGrantInput { + capsule: "vm-agent".to_string(), + resource: "elastos://mail/send".to_string(), + action: "execute".to_string(), + methods: vec!["send".to_string()], + ttl_secs: Some(3600), + agent_pubkey: None, + dispatch_limit: None, + responsible_entity: None, + }), + ) + .await + .expect("issue ok") + .0; + + // "Reboot" #1: a fresh service over the SAME snapshot — the mandate survives, live. + let rebooted = capability_manager + .standing_grant_service_with_persistence(®istry_path) + .unwrap(); + assert!( + rebooted.is_active(&out.grant_id), + "an issued mandate survives restart LIVE" + ); + + // Kill it through the real handler, then "reboot" #2: it STAYS dead. + let rev = revoke_standing_grant( + State(state.clone()), + Json(RevokeStandingGrantInput { + grant_id: out.grant_id.clone(), + }), + ) + .await + .expect("revoke ok") + .0; + assert!(rev.revoked); + let rebooted = capability_manager + .standing_grant_service_with_persistence(®istry_path) + .unwrap(); + assert!( + !rebooted.is_active(&out.grant_id), + "a revoked mandate is NEVER crash-revived" + ); + assert!( + rebooted + .get(&out.grant_id) + .expect("still queryable") + .revoked, + "the reloaded record is honestly marked revoked" + ); + } + + /// Like [`test_state`] but with a DURABLE (file-backed, signed) audit log, so the mandate's + /// grant/use/revoke land on a real chain a receipt can be exported from. + fn test_state_with_durable_audit(dir: &std::path::Path) -> CapabilityState { + let audit_log = std::sync::Arc::new( + elastos_runtime::primitives::audit::AuditLog::with_file(dir.join("audit.log")) + .expect("file-backed audit log"), + ); + let store = std::sync::Arc::new(elastos_runtime::capability::CapabilityStore::new()); + let metrics = + std::sync::Arc::new(elastos_runtime::primitives::metrics::MetricsManager::new()); + let capability_manager = + std::sync::Arc::new(CapabilityManager::new(store, audit_log.clone(), metrics)); + let standing_service = std::sync::Arc::new(capability_manager.standing_grant_service()); + let intent_executor = std::sync::Arc::new( + crate::intent_executor::MethodRegistryExecutor::production(audit_log.clone(), None), + ); + CapabilityState { + pending_store: std::sync::Arc::new(PendingRequestStore::new(audit_log.clone())), + capability_manager, + policy_evaluator: std::sync::Arc::new(PolicyEvaluator::new( + Box::new(elastos_runtime::capability::evaluator::ShellPassthroughVerifier), + audit_log, + )), + standing_service, + intent_executor, + spend_meter: None, + payment_ledger: None, + } + } + + /// Council S32 F3: the DID validator is syntactic anti-garbage — it accepts real DIDs and + /// rejects malformed ones (empty method, empty id, bad charset, over-long), and it NEVER + /// authenticates (a valid-shape DID for an entity that never consented still passes — that is + /// by design; the receipt records a DECLARATION, not consent). + #[test] + fn responsible_entity_validation_is_syntactic_and_fail_closed() { + // Accepted. + for ok in [ + "did:web:acme.example", + "did:key:z6Mk...", + "did:elastos:iabc123", + "did:web:acme.example%3A8443", + ] { + assert!( + validate_responsible_entity(Some(ok)).unwrap().is_some(), + "should accept {ok}" + ); + } + // None / blank ⇒ Ok(None) (optional field). + assert!(validate_responsible_entity(None).unwrap().is_none()); + assert!(validate_responsible_entity(Some(" ")).unwrap().is_none()); + // Rejected shapes (council F3): no method, no id, uppercase method, non-DID, bad char, long. + for bad in [ + "did:", + "did:web", + "did::x", + "did:WEB:x", + "notadid", + "did:web:a b", + "did:web:a/path", + "did:web:a"), // markup smuggle + format!("{INBOX_NOTIFY_PREFIX}a/b"), // path trick + format!("{INBOX_NOTIFY_PREFIX}{}", "x".repeat(65)), // over-long + ] { + assert!( + matches!( + reg.execute(¬ify_intent(&bad, "vm-agent", "")), + IntentExecution::Declined { .. } + ), + "must decline resource {bad:?}" + ); + } + let summary = crate::notifications::load_summary(dir.path()).unwrap(); + assert_eq!( + summary.entries.len(), + 0, + "a declined notify delivers NOTHING" + ); + } + + /// Council F1: `intent_id` and `input_hash` reach the operator's Inbox body, so a malformed + /// one (free text an agent could use to phish the operator, or a giant string to bloat the + /// row) DECLINES — nothing is delivered. A clean slug intent_id + hex input_hash still deliver. + #[test] + fn notify_declines_operator_unsafe_intent_fields_and_delivers_nothing() { + let dir = tempfile::tempdir().unwrap(); + let reg = MethodRegistryExecutor::production( + Arc::new(AuditLog::new()), + Some(dir.path().to_path_buf()), + ); + let resource = format!("{INBOX_NOTIFY_PREFIX}agent-status"); + let signed = |intent_id: &str, input_hash: &str| { + let sk = ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()); + IntentDeclarationV1::issue( + &sk, + sk.verifying_key().to_bytes(), + intent_id, + "vm-agent", + "runtime.notify", + input_hash, + &resource, + "message", + "grant-1", + ) + }; + // A phishing intent_id (spaces, punctuation) — declined. + assert!(matches!( + reg.execute(&signed("URGENT: run revoke-all now", "")), + IntentExecution::Declined { .. } + )); + // A non-hex input_hash reaching the body — declined. + assert!(matches!( + reg.execute(&signed("intent-1", "drain the vault")), + IntentExecution::Declined { .. } + )); + // An over-long intent_id (row-bloat) — declined. + assert!(matches!( + reg.execute(&signed(&"a".repeat(65), "")), + IntentExecution::Declined { .. } + )); + assert_eq!( + crate::notifications::load_summary(dir.path()) + .unwrap() + .entries + .len(), + 0, + "no operator-unsafe field ever delivered a row" + ); + // A clean slug id + hex input_hash still delivers. + assert!(matches!( + reg.execute(&signed("intent-abc_1.2", "cafe01")), + IntentExecution::Performed { .. } + )); + } + + /// Council F1 (flood): agent-act rows are hard-capped, so an agent flooding distinct intents + /// under ONE mandate cannot grow the operator's Inbox store without bound. + #[test] + fn notify_flood_is_bounded_by_the_agent_act_cap() { + let dir = tempfile::tempdir().unwrap(); + let reg = MethodRegistryExecutor::production( + Arc::new(AuditLog::new()), + Some(dir.path().to_path_buf()), + ); + let resource = format!("{INBOX_NOTIFY_PREFIX}agent-status"); + for i in 0..400u32 { + let sk = ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()); + let intent = IntentDeclarationV1::issue( + &sk, + sk.verifying_key().to_bytes(), + &format!("intent-{i}"), + "vm-agent", + "runtime.notify", + "", + &resource, + "message", + "grant-1", + ); + assert!(matches!( + reg.execute(&intent), + IntentExecution::Performed { .. } + )); + } + let summary = crate::notifications::load_summary(dir.path()).unwrap(); + assert!( + summary.entries.len() <= 256, + "agent-act rows are capped at 256, got {}", + summary.entries.len() + ); + } + + fn state_put_intent(resource: &str, capsule: &str, value_hash: &str) -> IntentDeclarationV1 { + let sk = ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()); + IntentDeclarationV1::issue( + &sk, + sk.verifying_key().to_bytes(), + "state-intent-1", + capsule, + "runtime.state_put", + value_hash, + resource, + "write", + "grant-1", + ) + } + + /// The SECOND side-effecting affordance: `runtime.state_put` PERFORMS iff the durable write + /// LANDS, and the written value is readable back — a real, observable mutation, principal-scoped. + #[test] + fn state_put_writes_durable_readable_state_and_reports_write() { + let dir = tempfile::tempdir().unwrap(); + let reg = MethodRegistryExecutor::production( + Arc::new(AuditLog::new()), + Some(dir.path().to_path_buf()), + ); + let resource = format!("{STATE_PUT_PREFIX}cursor"); + match reg.execute(&state_put_intent(&resource, "vm-agent", "cafe01")) { + IntentExecution::Performed { + action, + resource: r, + input_hash, + .. + } => { + assert_eq!(action, "write", "the act performed IS a write"); + assert_eq!(r, resource); + assert_eq!(input_hash, "cafe01"); + } + other => panic!("expected Performed, got {other:?}"), + } + // The side effect is REAL and readable back — principal-scoped to the acting capsule. + let got = crate::agent_store::get_agent_state(dir.path(), "vm-agent", "cursor") + .unwrap() + .expect("the written key is readable back"); + assert_eq!(got.value_hash, "cafe01"); + assert_eq!(got.grant_id, "grant-1"); + // A DIFFERENT capsule cannot read it — no cross-principal state leak. + assert!( + crate::agent_store::get_agent_state(dir.path(), "vm-other", "cursor") + .unwrap() + .is_none() + ); + } + + /// Fail-closed scoping: outside the store namespace, or with a key/value that could smuggle + /// free text into durable state, state_put DECLINES — and nothing is persisted. + #[test] + fn state_put_declines_bad_scopes_and_writes_nothing() { + let dir = tempfile::tempdir().unwrap(); + let reg = MethodRegistryExecutor::production( + Arc::new(AuditLog::new()), + Some(dir.path().to_path_buf()), + ); + for (resource, value) in [ + ("elastos://mail/send".to_string(), "aa".to_string()), // outside namespace + (STATE_PUT_PREFIX.to_string(), "aa".to_string()), // empty key + (format!("{STATE_PUT_PREFIX}a/b"), "aa".to_string()), // path trick + (format!("{STATE_PUT_PREFIX}k"), "not hex".to_string()), // free-text value + ( + format!("{STATE_PUT_PREFIX}{}", "x".repeat(65)), + "aa".to_string(), + ), // over-long key + ] { + assert!( + matches!( + reg.execute(&state_put_intent(&resource, "vm-agent", &value)), + IntentExecution::Declined { .. } + ), + "must decline resource {resource:?} value {value:?}" + ); + } + assert!( + crate::agent_store::get_agent_state(dir.path(), "vm-agent", "k") + .unwrap() + .is_none(), + "a declined state_put persists NOTHING" + ); + } + + /// The PERSISTED intent_id is bounded like every other agent-chosen stored string (council + /// carry-over): a giant/free-form intent_id declines rather than bloating durable state. + #[test] + fn state_put_declines_an_unbounded_intent_id() { + let dir = tempfile::tempdir().unwrap(); + let reg = MethodRegistryExecutor::production( + Arc::new(AuditLog::new()), + Some(dir.path().to_path_buf()), + ); + let resource = format!("{STATE_PUT_PREFIX}cursor"); + let sk = ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()); + let intent = IntentDeclarationV1::issue( + &sk, + sk.verifying_key().to_bytes(), + &"z".repeat(65), // over-long intent_id + "vm-agent", + "runtime.state_put", + "cafe01", + &resource, + "write", + "grant-1", + ); + assert!(matches!( + reg.execute(&intent), + IntentExecution::Declined { .. } + )); + assert!( + crate::agent_store::get_agent_state(dir.path(), "vm-agent", "cursor") + .unwrap() + .is_none(), + "a declined write persists nothing" + ); + } + + /// Without a data dir there is no store to write into — state_put is honestly UNWIRED. + #[test] + fn state_put_is_unwired_without_a_data_dir() { + let reg = MethodRegistryExecutor::production(Arc::new(AuditLog::new()), None); + let resource = format!("{STATE_PUT_PREFIX}cursor"); + assert!(matches!( + reg.execute(&state_put_intent(&resource, "vm-agent", "cafe01")), + IntentExecution::Declined { .. } + )); + } + + fn state_get_intent(resource: &str, capsule: &str, expected: &str) -> IntentDeclarationV1 { + let sk = ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()); + IntentDeclarationV1::issue( + &sk, + sk.verifying_key().to_bytes(), + "state-get-1", + capsule, + "runtime.state_get", + expected, // the value the agent EXPECTS (input_hash) + resource, + "read", + "grant-1", + ) + } + + /// Sprint 25: `runtime.state_get` is the READ side of the KV. It echoes the ACTUAL stored + /// value-hash (so the read reconciles Matched only when the agent declared the right value — an + /// attested "K = V" — proven end-to-end in the handler tests), Declines an absent key, and is + /// PRINCIPAL-SCOPED (an agent reads only its own state). + #[test] + fn state_get_reads_back_own_state_attested_and_principal_scoped() { + let dir = tempfile::tempdir().unwrap(); + let reg = MethodRegistryExecutor::production( + Arc::new(AuditLog::new()), + Some(dir.path().to_path_buf()), + ); + let resource = format!("{STATE_PUT_PREFIX}cursor"); + // Seed the store via the real state_put affordance. + assert!(matches!( + reg.execute(&state_put_intent(&resource, "vm-agent", "cafe01")), + IntentExecution::Performed { .. } + )); + + // A read → Performed echoing the ACTUAL stored value, action "read" — regardless of what + // the agent declared, so reconcile can Match (declared==actual) or Diverge (declared!=actual). + for declared in ["cafe01", "beef99", ""] { + match reg.execute(&state_get_intent(&resource, "vm-agent", declared)) { + IntentExecution::Performed { + action, + resource: r, + input_hash, + .. + } => { + assert_eq!(action, "read", "the act performed IS a read"); + assert_eq!(r, resource); + assert_eq!( + input_hash, "cafe01", + "echoes the REAL stored value-hash, not the agent's claim ({declared:?})" + ); + } + other => panic!("expected Performed for declared {declared:?}, got {other:?}"), + } + } + + // A DIFFERENT principal reading the same key → Declined (no cross-principal state read). + assert!( + matches!( + reg.execute(&state_get_intent(&resource, "vm-other", "cafe01")), + IntentExecution::Declined { .. } + ), + "an agent can only read its OWN state — never another principal's" + ); + + // An ABSENT key for the acting principal → Declined (authorized_not_performed). + let absent = format!("{STATE_PUT_PREFIX}never-written"); + assert!(matches!( + reg.execute(&state_get_intent(&absent, "vm-agent", "cafe01")), + IntentExecution::Declined { .. } + )); + } + + /// Fail-closed scoping for the read: outside the store namespace, a bad key, or an unbounded + /// expected-value DECLINES — the read affordance is as strict about its inputs as the write. + #[test] + fn state_get_declines_bad_scopes() { + let dir = tempfile::tempdir().unwrap(); + let reg = MethodRegistryExecutor::production( + Arc::new(AuditLog::new()), + Some(dir.path().to_path_buf()), + ); + for (resource, expected) in [ + ("elastos://mail/send".to_string(), "aa".to_string()), // outside namespace + (STATE_PUT_PREFIX.to_string(), "aa".to_string()), // empty key + (format!("{STATE_PUT_PREFIX}a/b"), "aa".to_string()), // path trick + (format!("{STATE_PUT_PREFIX}k"), "not hex".to_string()), // free-text expected value + ] { + assert!( + matches!( + reg.execute(&state_get_intent(&resource, "vm-agent", &expected)), + IntentExecution::Declined { .. } + ), + "must decline resource {resource:?} expected {expected:?}" + ); + } + } + + /// Without a data dir there is no store to read — state_get is honestly UNWIRED. + #[test] + fn state_get_is_unwired_without_a_data_dir() { + let reg = MethodRegistryExecutor::production(Arc::new(AuditLog::new()), None); + let resource = format!("{STATE_PUT_PREFIX}cursor"); + assert!(matches!( + reg.execute(&state_get_intent(&resource, "vm-agent", "cafe01")), + IntentExecution::Declined { .. } + )); + } + + // ── Sprint 27: the spend-capped `runtime.pay` affordance ────────────────────────────────── + use elastos_runtime::primitives::spend::SpendMeter; + + /// A payment rail that always refuses PROVABLY-NOT-CHARGED — to prove the meter is REFUNDED + /// exactly (and only) on that classification. + struct FailingProvider; + impl PaymentProvider for FailingProvider { + fn rail(&self) -> crate::payment_ledger::PaymentRail { + crate::payment_ledger::PaymentRail::Unknown + } + fn pay(&self, _payee: &str, _amount: u64, _key: &str) -> Result { + Err(PayError::NotCharged("rail unavailable".to_string())) + } + } + + fn pay_intent(payee: &str, capsule: &str, amount: &str) -> IntentDeclarationV1 { + let sk = ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()); + IntentDeclarationV1::issue( + &sk, + sk.verifying_key().to_bytes(), + "pay-intent-1", + capsule, + "runtime.pay", + amount, // the AMOUNT rides in input_hash + &format!("{PAY_PREFIX}{payee}"), + "execute", + "grant-1", + ) + } + + fn pay_registry(meter: Arc) -> (MethodRegistryExecutor, Arc) { + let provider = Arc::new(MockPaymentProvider::default()); + let reg = MethodRegistryExecutor::production(Arc::new(AuditLog::new()), None) + .with_payments( + meter, + provider.clone(), + Arc::new(crate::payment_ledger::PaymentLedger::new()), + ); + (reg, provider) + } + + /// `runtime.pay` within the cap: the meter is debited and the rail moves the money once — the + /// receipt reports the exact amount + payee (Performed as `execute`). + #[test] + fn pay_within_cap_charges_the_meter_and_moves_money_once() { + let meter = Arc::new(SpendMeter::new()); + meter.set_budget("vm-agent", 500).unwrap(); + let (reg, provider) = pay_registry(meter.clone()); + match reg.execute(&pay_intent("acme-vendor", "vm-agent", "200")) { + IntentExecution::Performed { + action, + resource, + input_hash, + .. + } => { + assert_eq!(action, "execute"); + assert_eq!(resource, format!("{PAY_PREFIX}acme-vendor")); + assert_eq!( + input_hash, "200", + "the receipt names the amount actually paid" + ); + } + other => panic!("expected Performed, got {other:?}"), + } + assert_eq!( + meter.remaining("vm-agent"), + 300, + "the cap was debited by exactly the amount" + ); + assert_eq!( + *provider.payments.lock().unwrap(), + vec![("acme-vendor".to_string(), 200)], + "the rail moved the money exactly once" + ); + } + + /// Over the cap: the payment is REFUSED, the meter is untouched, and NO money moves — a + /// fail-closed signed refusal, the whole point of the affordance. + #[test] + fn pay_over_cap_is_refused_and_moves_no_money() { + let meter = Arc::new(SpendMeter::new()); + meter.set_budget("vm-agent", 100).unwrap(); + let (reg, provider) = pay_registry(meter.clone()); + assert!(matches!( + reg.execute(&pay_intent("acme-vendor", "vm-agent", "150")), + IntentExecution::Declined { .. } + )); + assert_eq!( + meter.remaining("vm-agent"), + 100, + "a refused payment does not touch the cap" + ); + assert!( + provider.payments.lock().unwrap().is_empty(), + "no money moved over the cap" + ); + } + + /// An unprovisioned capsule has ZERO budget (fail-closed) — it cannot pay a cent until the + /// operator provisions a cap. + #[test] + fn pay_unprovisioned_capsule_is_fail_closed() { + let meter = Arc::new(SpendMeter::new()); + let (reg, provider) = pay_registry(meter); + assert!(matches!( + reg.execute(&pay_intent("acme-vendor", "vm-nobudget", "1")), + IntentExecution::Declined { .. } + )); + assert!(provider.payments.lock().unwrap().is_empty()); + } + + /// If the RAIL fails after the reservation, the meter is REFUNDED (no money moved) so the budget + /// is made whole — a later in-budget payment still works. + #[test] + fn pay_rail_failure_refunds_the_reservation() { + let meter = Arc::new(SpendMeter::new()); + meter.set_budget("vm-agent", 100).unwrap(); + let reg = MethodRegistryExecutor::production(Arc::new(AuditLog::new()), None) + .with_payments( + meter.clone(), + Arc::new(FailingProvider), + Arc::new(crate::payment_ledger::PaymentLedger::new()), + ); + assert!(matches!( + reg.execute(&pay_intent("acme-vendor", "vm-agent", "40")), + IntentExecution::Declined { .. } + )); + assert_eq!( + meter.remaining("vm-agent"), + 100, + "a failed rail refunds the reservation — the cap is made whole, no phantom spend" + ); + } + + /// A rail that PANICS is INDETERMINATE (S29 — supersedes the S27 refund-on-panic fold): with a + /// REAL rail the panic may happen AFTER the charge posted, and a refund would let total real + /// spend exceed the cap (invariant a). The reservation is KEPT and the reason says so honestly. + #[test] + fn pay_rail_panic_keeps_the_reservation_as_indeterminate() { + struct PanickingProvider; + impl PaymentProvider for PanickingProvider { + fn rail(&self) -> crate::payment_ledger::PaymentRail { + crate::payment_ledger::PaymentRail::Unknown + } + fn pay(&self, _payee: &str, _amount: u64, _key: &str) -> Result { + panic!("rail exploded mid-charge") + } + } + let meter = Arc::new(SpendMeter::new()); + meter.set_budget("vm-agent", 100).unwrap(); + let reg = MethodRegistryExecutor::production(Arc::new(AuditLog::new()), None) + .with_payments( + meter.clone(), + Arc::new(PanickingProvider), + Arc::new(crate::payment_ledger::PaymentLedger::new()), + ); + match reg.execute(&pay_intent("acme-vendor", "vm-agent", "40")) { + IntentExecution::Declined { reason } => { + assert!( + reason.contains("INDETERMINATE") && reason.contains("cap remains debited"), + "the signed reason must state indeterminacy + kept reservation: {reason}" + ); + } + other => panic!("expected Declined, got {other:?}"), + } + assert_eq!( + meter.remaining("vm-agent"), + 60, + "the reservation is KEPT — a maybe-charged payment must not restore headroom" + ); + } + + /// An INDETERMINATE rail outcome (timeout/5xx) keeps the reservation and names the idempotency + /// key for reconciliation — refunding against money that may have moved would break the cap. + #[test] + fn pay_indeterminate_outcome_keeps_the_reservation() { + struct IndeterminateProvider; + impl PaymentProvider for IndeterminateProvider { + fn rail(&self) -> crate::payment_ledger::PaymentRail { + crate::payment_ledger::PaymentRail::Unknown + } + fn pay(&self, _payee: &str, _amount: u64, _key: &str) -> Result { + Err(PayError::Indeterminate("timeout after send".to_string())) + } + } + let meter = Arc::new(SpendMeter::new()); + meter.set_budget("vm-agent", 100).unwrap(); + let reg = MethodRegistryExecutor::production(Arc::new(AuditLog::new()), None) + .with_payments( + meter.clone(), + Arc::new(IndeterminateProvider), + Arc::new(crate::payment_ledger::PaymentLedger::new()), + ); + match reg.execute(&pay_intent("acme-vendor", "vm-agent", "40")) { + IntentExecution::Declined { reason } => { + assert!( + reason.contains("INDETERMINATE") && reason.contains("idempotency key flint-"), + "the reason names the indeterminacy and the reconciliation key: {reason}" + ); + assert!( + !reason.contains("refunded"), + "an indeterminate outcome must never claim a refund: {reason}" + ); + } + other => panic!("expected Declined, got {other:?}"), + } + assert_eq!(meter.remaining("vm-agent"), 60, "the reservation is kept"); + } + + /// The HTTP rail connector's two-generals classification, exercised against a REAL local HTTP + /// server: 2xx confirms, 4xx is provably-not-charged, 5xx is indeterminate, connection-refused + /// (nothing sent) is provably-not-charged, and a timeout after send is indeterminate. The + /// idempotency key must reach the wire as the Idempotency-Key header. + #[test] + fn http_rail_classifies_outcomes_two_generals_honestly() { + use std::io::{Read as _, Write as _}; + // A one-shot local HTTP server: returns `status`, captures the request head. + fn serve_once(status: &'static str) -> (String, std::sync::mpsc::Receiver) { + let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); + let addr = listener.local_addr().unwrap(); + let (tx, rx) = std::sync::mpsc::channel(); + std::thread::spawn(move || { + let (mut stream, _) = listener.accept().unwrap(); + let mut buf = [0u8; 4096]; + let n = stream.read(&mut buf).unwrap_or(0); + let _ = tx.send(String::from_utf8_lossy(&buf[..n]).to_string()); + let body = "rail-ref-123"; + let _ = write!( + stream, + "HTTP/1.1 {status}\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}", + body.len() + ); + }); + (format!("http://{addr}/pay"), rx) + } + + // 2xx → Ok, with the idempotency key on the wire. + let (url, rx) = serve_once("200 OK"); + let ok = HttpPaymentProvider::new(url, Some("tok".into())) + .pay("acme-vendor", 200, "flint-abc123") + .expect("2xx confirms the charge"); + assert_eq!(ok, "rail-ref-123", "the rail reference comes back"); + let req = rx.recv().unwrap(); + assert!( + req.contains("idempotency-key: flint-abc123") + || req.contains("Idempotency-Key: flint-abc123"), + "the idempotency key reaches the wire: {req}" + ); + assert!(req.contains("\"payee\":\"acme-vendor\"") && req.contains("\"amount\":200")); + + // 4xx → the order was REJECTED before processing: provably not charged. + let (url, _rx) = serve_once("422 Unprocessable Entity"); + assert!(matches!( + HttpPaymentProvider::new(url, None).pay("acme-vendor", 200, "k"), + Err(PayError::NotCharged(_)) + )); + + // 5xx → the order REACHED the rail and then something broke: indeterminate. + let (url, _rx) = serve_once("500 Internal Server Error"); + assert!(matches!( + HttpPaymentProvider::new(url, None).pay("acme-vendor", 200, "k"), + Err(PayError::Indeterminate(_)) + )); + + // Connection refused → nothing was ever sent: provably not charged. + let dead = { + let l = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); + let a = l.local_addr().unwrap(); + drop(l); + format!("http://{a}/pay") + }; + assert!(matches!( + HttpPaymentProvider::new(dead, None).pay("acme-vendor", 200, "k"), + Err(PayError::NotCharged(_)) + )); + + // Timeout after the request was sent → indeterminate (the charge may have posted). + let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); + let addr = listener.local_addr().unwrap(); + std::thread::spawn(move || { + let (stream, _) = listener.accept().unwrap(); + std::thread::sleep(std::time::Duration::from_millis(1500)); + drop(stream); // accept, read nothing back, never respond + }); + assert!(matches!( + HttpPaymentProvider::new(format!("http://{addr}/pay"), None) + .with_timeout(std::time::Duration::from_millis(300)) + .pay("acme-vendor", 200, "k"), + Err(PayError::Indeterminate(_)) + )); + + // A REDIRECT is never followed (council S29 F6): the default policy would re-issue the + // POST as a GET whose 200 mints a Performed receipt off a login page. 3xx ⇒ indeterminate. + let (url, _rx) = serve_once("302 Found"); + assert!(matches!( + HttpPaymentProvider::new(url, None).pay("acme-vendor", 200, "k"), + Err(PayError::Indeterminate(_)) + )); + + // A malformed endpoint (builder error — nothing ever left the process) is provably NOT + // charged (council S29 F3), never "the charge may have posted". + assert!(matches!( + HttpPaymentProvider::new("not a url at all".to_string(), None).pay( + "acme-vendor", + 200, + "k" + ), + Err(PayError::NotCharged(_)) + )); + } + + /// Council S29 red-team F2: concurrent in-flight payments are BOUNDED fail-closed — the 9th + /// while 8 block on the rail is REFUSED with nothing debited and nothing sent; slots release + /// when the rail returns. + #[test] + fn pay_in_flight_concurrency_is_bounded_fail_closed() { + struct BlockingProvider { + entered: std::sync::atomic::AtomicUsize, + rx: std::sync::Mutex>, + } + impl PaymentProvider for BlockingProvider { + fn rail(&self) -> crate::payment_ledger::PaymentRail { + crate::payment_ledger::PaymentRail::Unknown + } + fn pay(&self, _payee: &str, _amount: u64, _key: &str) -> Result { + self.entered + .fetch_add(1, std::sync::atomic::Ordering::SeqCst); + let _ = self.rx.lock().unwrap().recv(); // hold the slot until released + Ok("ok".to_string()) + } + } + let (tx, rx) = std::sync::mpsc::channel(); + let provider = Arc::new(BlockingProvider { + entered: std::sync::atomic::AtomicUsize::new(0), + rx: std::sync::Mutex::new(rx), + }); + let meter = Arc::new(SpendMeter::new()); + meter.set_budget("vm-agent", 1000).unwrap(); + let reg = Arc::new( + MethodRegistryExecutor::production(Arc::new(AuditLog::new()), None).with_payments( + meter.clone(), + provider.clone(), + Arc::new(crate::payment_ledger::PaymentLedger::new()), + ), + ); + let mut handles = Vec::new(); + for _ in 0..8 { + let r = reg.clone(); + handles.push(std::thread::spawn(move || { + r.execute(&pay_intent("acme-vendor", "vm-agent", "10")) + })); + } + // Wait until all 8 are genuinely in-flight (inside the rail call, slots held). + while provider.entered.load(std::sync::atomic::Ordering::SeqCst) < 8 { + std::thread::yield_now(); + } + match reg.execute(&pay_intent("acme-vendor", "vm-agent", "10")) { + IntentExecution::Declined { reason } => { + assert!( + reason.contains("in-flight"), + "the 9th concurrent payment is refused by the bound: {reason}" + ); + } + other => panic!("expected Declined, got {other:?}"), + } + assert_eq!( + meter.remaining("vm-agent"), + 1000 - 80, + "the refused payment debited NOTHING (only the 8 in-flight reservations)" + ); + for _ in 0..8 { + tx.send(()).unwrap(); + } + for h in handles { + assert!(matches!( + h.join().unwrap(), + IntentExecution::Performed { .. } + )); + } + // Slots released: a new payment goes through again. + drop(tx); + assert!(matches!( + reg.execute(&pay_intent("acme-vendor", "vm-agent", "10")), + IntentExecution::Performed { .. } + )); + } + + /// The idempotency key is derived from the intent's SIGNATURE — unique per signed declaration + /// (an intent_id can recycle out of the replay window; a signature cannot), so the rail can + /// dedupe without ever double-moving money for one signed intent. + #[test] + fn pay_idempotency_key_is_signature_derived_and_unique_per_signed_intent() { + #[derive(Default)] + struct KeyRecordingProvider(std::sync::Mutex>); + impl PaymentProvider for KeyRecordingProvider { + fn rail(&self) -> crate::payment_ledger::PaymentRail { + crate::payment_ledger::PaymentRail::Unknown + } + fn pay(&self, _payee: &str, _amount: u64, key: &str) -> Result { + self.0.lock().unwrap().push(key.to_string()); + Ok("ok".to_string()) + } + } + let meter = Arc::new(SpendMeter::new()); + meter.set_budget("vm-agent", 100).unwrap(); + let provider = Arc::new(KeyRecordingProvider::default()); + let reg = MethodRegistryExecutor::production(Arc::new(AuditLog::new()), None) + .with_payments( + meter, + provider.clone(), + Arc::new(crate::payment_ledger::PaymentLedger::new()), + ); + let i1 = pay_intent("acme-vendor", "vm-agent", "10"); + let i2 = pay_intent("acme-vendor", "vm-agent", "10"); // same shape, fresh key+signature + assert!(matches!( + reg.execute(&i1), + IntentExecution::Performed { .. } + )); + assert!(matches!( + reg.execute(&i2), + IntentExecution::Performed { .. } + )); + let keys = provider.0.lock().unwrap().clone(); + assert_eq!(keys.len(), 2); + assert_eq!(keys[0], format!("flint-{}", i1.signature)); + assert_eq!(keys[1], format!("flint-{}", i2.signature)); + assert_ne!( + keys[0], keys[1], + "distinct signed intents get distinct keys" + ); + } + + /// Council S28 F3: when the rail fails AND the durable refund cannot persist, the signed reason + /// must NOT claim "spend refunded" — the honest record is that the cap remains debited. The + /// provider itself destroys the meter's directory mid-payment (between the persisted + /// reservation and the refund), the only real window this can happen in. + #[test] + fn pay_rail_failure_with_unpersistable_refund_is_recorded_honestly() { + struct DirDestroyingFailingProvider(std::path::PathBuf); + impl PaymentProvider for DirDestroyingFailingProvider { + fn rail(&self) -> crate::payment_ledger::PaymentRail { + crate::payment_ledger::PaymentRail::Unknown + } + fn pay(&self, _payee: &str, _amount: u64, _key: &str) -> Result { + std::fs::remove_dir_all(&self.0).expect("kill the meter's persist target"); + Err(PayError::NotCharged("rail unavailable".to_string())) + } + } + let dir = tempfile::tempdir().unwrap(); + let sub = dir.path().join("meter"); + std::fs::create_dir(&sub).unwrap(); + let meter = Arc::new( + elastos_runtime::primitives::spend::SpendMeter::open_durable( + sub.join("spend_meter.json"), + ) + .unwrap(), + ); + meter.set_budget("vm-agent", 100).unwrap(); + let reg = MethodRegistryExecutor::production(Arc::new(AuditLog::new()), None) + .with_payments( + meter.clone(), + Arc::new(DirDestroyingFailingProvider(sub)), + Arc::new(crate::payment_ledger::PaymentLedger::new()), + ); + match reg.execute(&pay_intent("acme-vendor", "vm-agent", "40")) { + IntentExecution::Declined { reason } => { + assert!( + reason.contains("the cap remains debited"), + "the signed reason must say the cap remains debited, got: {reason}" + ); + assert!( + !reason.contains("spend refunded"), + "the signed reason must NOT claim a refund that is not in force: {reason}" + ); + } + other => panic!("expected Declined, got {other:?}"), + } + assert_eq!( + meter.remaining("vm-agent"), + 60, + "the unpersistable refund was rolled back — the cap really does remain debited" + ); + } + + /// Fail-closed scoping: outside the pay namespace, a bad payee, a non-integer amount, a zero + /// amount, or a NON-CANONICAL amount (leading zero / sign / space — F4) all DECLINE, and none + /// debits the cap. (Canonical form is required so a Performed pay always reconciles Matched.) + #[test] + fn pay_declines_bad_scope_and_amount() { + let meter = Arc::new(SpendMeter::new()); + meter.set_budget("vm-agent", 1000).unwrap(); + let (reg, provider) = pay_registry(meter.clone()); + let sk = ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()); + let bad = |resource: &str, amount: &str| { + IntentDeclarationV1::issue( + &sk, + sk.verifying_key().to_bytes(), + "pi", + "vm-agent", + "runtime.pay", + amount, + resource, + "execute", + "grant-1", + ) + }; + for (resource, amount) in [ + ("elastos://mail/send".to_string(), "10".to_string()), // outside namespace + (PAY_PREFIX.to_string(), "10".to_string()), // empty payee + (format!("{PAY_PREFIX}a/b"), "10".to_string()), // path trick in payee + (format!("{PAY_PREFIX}acme"), "not-a-number".to_string()), // non-integer amount + (format!("{PAY_PREFIX}acme"), "0".to_string()), // zero amount + (format!("{PAY_PREFIX}acme"), "0200".to_string()), // non-canonical (leading zero) — F4 + (format!("{PAY_PREFIX}acme"), "+200".to_string()), // non-canonical (sign) — F4 + (format!("{PAY_PREFIX}acme"), " 200".to_string()), // non-canonical (space) — F4 + ] { + assert!( + matches!( + reg.execute(&bad(&resource, &amount)), + IntentExecution::Declined { .. } + ), + "must decline resource {resource:?} amount {amount:?}" + ); + } + assert_eq!( + meter.remaining("vm-agent"), + 1000, + "no declined pay ever touched the cap" + ); + assert!(provider.payments.lock().unwrap().is_empty()); + } + + /// Without a wired meter/provider, `runtime.pay` is honestly UNWIRED ⇒ Declined ⇒ Undelivered. + #[test] + fn pay_is_unwired_without_with_payments() { + let reg = MethodRegistryExecutor::production(Arc::new(AuditLog::new()), None); + assert!(matches!( + reg.execute(&pay_intent("acme-vendor", "vm-agent", "10")), + IntentExecution::Declined { .. } + )); + } + + /// A write the store cannot persist DECLINES with the true reason — Performed only for a write + /// that landed. (Seam: a FILE squatting where the store's directory tree must be created.) + #[test] + fn state_put_declines_when_the_store_write_fails() { + let dir = tempfile::tempdir().unwrap(); + std::fs::write(dir.path().join("Local"), b"squat").unwrap(); + let reg = MethodRegistryExecutor::production( + Arc::new(AuditLog::new()), + Some(dir.path().to_path_buf()), + ); + let resource = format!("{STATE_PUT_PREFIX}cursor"); + match reg.execute(&state_put_intent(&resource, "vm-agent", "cafe01")) { + IntentExecution::Declined { reason } => { + assert!( + reason.contains("could not be persisted"), + "true reason: {reason}" + ); + } + other => panic!("an unlanded write must Decline, got {other:?}"), + } + } + + /// Without a data dir there is no Inbox store to deliver into — the method is honestly + /// UNWIRED (⇒ Undelivered), never a fabricated delivery. + #[test] + fn notify_is_unwired_without_a_data_dir() { + let reg = MethodRegistryExecutor::production(Arc::new(AuditLog::new()), None); + let resource = format!("{INBOX_NOTIFY_PREFIX}agent-status"); + assert!(matches!( + reg.execute(¬ify_intent(&resource, "vm-agent", "")), + IntentExecution::Declined { .. } + )); + } + + /// A delivery the store cannot persist is DECLINED with the true reason — Performed is only + /// ever reported for a write that landed. (Seam: a FILE squatting where the notifications + /// directory tree must be created makes the store write fail, root or not.) + #[test] + fn notify_declines_when_the_store_write_fails() { + let dir = tempfile::tempdir().unwrap(); + // The notifications store lives under /Local/... — squat a FILE at Local. + std::fs::write(dir.path().join("Local"), b"squat").unwrap(); + let reg = MethodRegistryExecutor::production( + Arc::new(AuditLog::new()), + Some(dir.path().to_path_buf()), + ); + let resource = format!("{INBOX_NOTIFY_PREFIX}agent-status"); + match reg.execute(¬ify_intent(&resource, "vm-agent", "")) { + IntentExecution::Declined { reason } => { + assert!( + reason.contains("could not be delivered"), + "the true failure is named: {reason}" + ); + } + other => panic!("an unlanded delivery must Decline, got {other:?}"), + } + } + + #[test] + fn content_seen_tracks_real_state_not_the_declaration() { + use elastos_runtime::capability::IntentDeclarationV1; + let dir = tempfile::tempdir().unwrap(); + let log = Arc::new(AuditLog::with_file(dir.path().join("audit.log")).unwrap()); + // Record that principal "vm-agent" SUCCESSFULLY OPENED one content id. + log.content_open("sess", "vm-agent", "QmSEEN", "view", "opened", "prov", None) + .unwrap(); + let reg = MethodRegistryExecutor::production(log, None); + + // Intent resource is a content-access-CHECK ref: prefix + content id. + let check = |content_id: &str| format!("{CONTENT_ACCESS_CHECK_PREFIX}{content_id}"); + let intent_for = |resource: String, capsule: &str| { + let sk = ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()); + IntentDeclarationV1::issue( + &sk, + sk.verifying_key().to_bytes(), + "i", + capsule, + "runtime.content_seen", + "", + &resource, + "read", + "grant-1", + ) + }; + // The SAME method + declaration shape reconciles differently based on REAL state: + match reg.execute(&intent_for(check("QmSEEN"), "vm-agent")) { + IntentExecution::Performed { + resource, action, .. + } => { + assert_eq!(resource, check("QmSEEN")); // the CHECK resource, honestly echoed + assert_eq!(action, "read"); + } + other => panic!("expected Performed for a seen content id, got {other:?}"), + } + // Never-opened id ⇒ Declined. + assert!(matches!( + reg.execute(&intent_for(check("QmNEVER"), "vm-agent")), + IntentExecution::Declined { .. } + )); + // PRINCIPAL-SCOPED: a DIFFERENT capsule asking about the same id gets Declined — no + // cross-principal existence oracle. + assert!( + matches!( + reg.execute(&intent_for(check("QmSEEN"), "vm-other")), + IntentExecution::Declined { .. } + ), + "content_seen must not reveal another principal's access" + ); + } + // ─────────────────────── runtime.market_quote (Sprint 39) ─────────────────────── + + struct ScriptedQuoter(Result); + impl crate::market_quote::MarketQuoter for ScriptedQuoter { + fn quote(&self, _: &str) -> Result { + self.0.clone() + } + } + + fn quote_intent(asset: &str, declared: &str) -> IntentDeclarationV1 { + let sk = ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()); + IntentDeclarationV1::issue( + &sk, + sk.verifying_key().to_bytes(), + "quote-intent-1", + "vm-shopper", + "runtime.market_quote", + declared, + &format!("{PAY_PREFIX}{asset}"), + "read", + "grant-1", + ) + } + + fn quote_registry( + outcome: Result, + ) -> MethodRegistryExecutor { + MethodRegistryExecutor::new() + .with_market_quotes(Arc::default(), Arc::new(ScriptedQuoter(outcome))) + } + + fn terms_5_usdc() -> crate::api::buy_authority::BuyQuote { + crate::api::buy_authority::BuyQuote { + price: "5000000".to_string(), + pay_token: "0xUSDC".to_string(), + supply: 3, + } + } + + /// Discovery mode ("" declared): the read performs AS DECLARED (input_hash echo "") so it + /// reconciles Matched, and the terms reach the agent ONLY via the explicit disclosure. + #[test] + fn market_quote_discovery_returns_terms_via_the_disclosure_channel() { + let exec = quote_registry(Ok(terms_5_usdc())); + match exec.execute("e_intent("QmMovie", "")) { + IntentExecution::Performed { + input_hash, + action, + agent_visible_report, + rail_ref, + .. + } => { + assert_eq!(input_hash, "", "discovery echoes the declaration — Matched"); + assert_eq!(action, "read"); + assert_eq!( + agent_visible_report.as_deref(), + Some("price=5000000;tok=0xUSDC;supply=3"), + "the terms travel via the EXPLICIT disclosure channel" + ); + assert!(rail_ref.is_none(), "a quote settles nothing — no rail_ref"); + } + other => panic!("expected Performed, got {other:?}"), + } + } + + /// Attested mode: declaring the CURRENT terms Matches (the echo equals the declaration); + /// declaring STALE terms gets the ACTUAL terms echoed — the reconciliation Diverges, never a + /// fabricated match. + #[test] + fn market_quote_attested_mode_echoes_actual_terms() { + let exec = quote_registry(Ok(terms_5_usdc())); + let current = "price=5000000;tok=0xUSDC;supply=3"; + match exec.execute("e_intent("QmMovie", current)) { + IntentExecution::Performed { input_hash, .. } => { + assert_eq!( + input_hash, current, + "believed-correct terms reconcile Matched" + ); + } + other => panic!("expected Performed, got {other:?}"), + } + match exec.execute("e_intent("QmMovie", "price=1;tok=0xUSDC;supply=3")) { + IntentExecution::Performed { input_hash, .. } => { + assert_eq!( + input_hash, current, + "stale belief: the ACTUAL terms are echoed — Diverged, never fabricated" + ); + } + other => panic!("expected Performed, got {other:?}"), + } + } + + /// A failed read (no listing / chain unreachable) DECLINES with the bounded error — a quote + /// is performed only when it truly returned terms. And the pay namespace is the boundary: + /// a non-pay resource declines before any read. + #[test] + fn market_quote_declines_on_read_failure_and_outside_the_pay_namespace() { + let exec = quote_registry(Err("no active listing".to_string())); + match exec.execute("e_intent("QmMovie", "")) { + IntentExecution::Declined { reason } => { + assert!( + reason.contains("no active listing"), + "honest reason: {reason}" + ); + } + other => panic!("expected Declined, got {other:?}"), + } + let sk = ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()); + let outside = IntentDeclarationV1::issue( + &sk, + sk.verifying_key().to_bytes(), + "quote-intent-2", + "vm-shopper", + "runtime.market_quote", + "", + "elastos://runtime/state/secret-key", + "read", + "grant-1", + ); + match quote_registry(Ok(terms_5_usdc())).execute(&outside) { + IntentExecution::Declined { reason } => { + assert!(reason.contains("must be"), "namespace-bounded: {reason}"); + } + other => panic!("expected Declined, got {other:?}"), + } + } + + /// The affordance rides the ONE quote spine: a cached quote is served with NO quoter call, + /// and a fresh in-flight claim by another consumer declines rather than duplicating the read. + #[test] + fn market_quote_shares_the_single_flight_cache() { + struct CountingQuoter(std::sync::atomic::AtomicUsize); + impl crate::market_quote::MarketQuoter for CountingQuoter { + fn quote(&self, _: &str) -> Result { + self.0.fetch_add(1, std::sync::atomic::Ordering::SeqCst); + Ok(crate::api::buy_authority::BuyQuote { + price: "7".to_string(), + pay_token: "native".to_string(), + supply: 1, + }) + } + } + let cache: crate::market_quote::MarketQuoteCache = Arc::default(); + let quoter = Arc::new(CountingQuoter(std::sync::atomic::AtomicUsize::new(0))); + let exec = MethodRegistryExecutor::new().with_market_quotes(cache.clone(), quoter.clone()); + assert!(matches!( + exec.execute("e_intent("QmA", "")), + IntentExecution::Performed { .. } + )); + assert!(matches!( + exec.execute("e_intent("QmA", "")), + IntentExecution::Performed { .. } + )); + assert_eq!( + quoter.0.load(std::sync::atomic::Ordering::SeqCst), + 1, + "the second quote is a cache hit — one live read per asset per window" + ); + // Another consumer (the panel) holds the in-flight claim for QmB ⇒ the agent's quote + // declines with retry rather than duplicating the chain read. + crate::market_quote::claim_or_serve(&cache, "QmB", crate::market_quote::now_unix(), true); + match exec.execute("e_intent("QmB", "")) { + IntentExecution::Declined { reason } => { + assert!( + reason.contains("in progress"), + "single-flight respected: {reason}" + ); + } + other => panic!("expected Declined, got {other:?}"), + } + } + /// Council S39 fold (red-team F2): terms the QUOTE SOURCE returns are held to the same bound + /// as the agent's declaration before they are signed/disclosed — out-of-bound terms refuse, + /// they never land on the chain or in the response. + #[test] + fn market_quote_refuses_malformed_terms_from_the_quote_source() { + let huge = quote_registry(Ok(crate::api::buy_authority::BuyQuote { + price: "9".repeat(500), + pay_token: "0xUSDC".to_string(), + supply: 1, + })); + match huge.execute("e_intent("QmMovie", "")) { + IntentExecution::Declined { reason } => { + assert!( + reason.contains("malformed terms"), + "bounded refusal: {reason}" + ); + } + other => panic!("expected Declined on oversized terms, got {other:?}"), + } + let nonprintable = quote_registry(Ok(crate::api::buy_authority::BuyQuote { + price: "5\u{7}00".to_string(), // a control byte from a hostile quote source + pay_token: "0xUSDC".to_string(), + supply: 1, + })); + match nonprintable.execute("e_intent("QmMovie", "")) { + IntentExecution::Declined { reason } => { + assert!( + reason.contains("malformed terms"), + "charset refusal: {reason}" + ); + } + other => panic!("expected Declined on non-printable terms, got {other:?}"), + } + } + + /// Council S39 fold (red-team F1): concurrent quote reads are BOUNDED like payments — with + /// every slot parked on a hung read, the next quote refuses with retry instead of parking + /// another blocking thread; released slots admit again. + #[test] + fn market_quote_inflight_reads_are_bounded_fail_closed() { + use std::sync::atomic::{AtomicUsize, Ordering}; + use std::sync::mpsc; + + /// A quoter that parks until released, counting entries. + struct ParkedQuoter { + entered: AtomicUsize, + release: std::sync::Mutex>, + } + impl crate::market_quote::MarketQuoter for ParkedQuoter { + fn quote(&self, _: &str) -> Result { + self.entered.fetch_add(1, Ordering::SeqCst); + // Park until the test releases us (bounded by the recv timeout below). + let _ = self + .release + .lock() + .unwrap() + .recv_timeout(std::time::Duration::from_secs(30)); + Ok(crate::api::buy_authority::BuyQuote { + price: "1".to_string(), + pay_token: "native".to_string(), + supply: 1, + }) + } + } + let (tx, rx) = mpsc::channel::<()>(); + let quoter = Arc::new(ParkedQuoter { + entered: AtomicUsize::new(0), + release: std::sync::Mutex::new(rx), + }); + let exec = Arc::new( + MethodRegistryExecutor::new().with_market_quotes(Arc::default(), quoter.clone()), + ); + + // Park 8 reads on 8 DISTINCT assets (single-flight dedups per asset, so distinct assets + // are what can stack threads — exactly the attack the bound closes). + let mut handles = Vec::new(); + for i in 0..8 { + let exec = exec.clone(); + handles.push(std::thread::spawn(move || { + exec.execute("e_intent(&format!("Qm{i}"), "")) + })); + } + // Wait until all 8 are genuinely inside the quoter (parked on the channel). + let deadline = std::time::Instant::now() + std::time::Duration::from_secs(10); + while quoter.entered.load(Ordering::SeqCst) < 8 { + assert!( + std::time::Instant::now() < deadline, + "parked readers never arrived" + ); + std::thread::yield_now(); + } + + // The 9th DISTINCT asset: every slot is parked ⇒ refuse with retry, never a 9th thread. + match exec.execute("e_intent("Qm-ninth", "")) { + IntentExecution::Declined { reason } => { + assert!( + reason.contains("already") && reason.contains("in-flight"), + "the bound refuses, fail-closed: {reason}" + ); + } + other => panic!("expected the in-flight bound to refuse, got {other:?}"), + } + assert_eq!( + quoter.entered.load(Ordering::SeqCst), + 8, + "the 9th quote never reached the quote source" + ); + + // Release the parked readers; the slots free and a new quote is admitted again. + for _ in 0..8 { + let _ = tx.send(()); + } + for h in handles { + let _ = h.join().unwrap(); + } + // Disconnect the channel so the admitted after-quote returns immediately instead of + // parking out its full recv timeout. + drop(tx); + match exec.execute("e_intent("Qm-after", "")) { + IntentExecution::Performed { .. } => {} + other => panic!("released slots must admit again, got {other:?}"), + } + } + + // ─────────────────────── runtime.negotiate (Sprint 50 — Track D3) ─────────────────────── + + use crate::negotiation::{NegotiationOutcome, Negotiator}; + + /// A seller that returns a scripted outcome and COUNTS how many times it was called — so a test + /// can prove the runtime refused an over-cap offer BEFORE the seller ever saw it. + struct CountingNegotiator { + outcome: std::sync::Mutex, + calls: std::sync::atomic::AtomicUsize, + } + impl CountingNegotiator { + fn new(outcome: NegotiationOutcome) -> Arc { + Arc::new(Self { + outcome: std::sync::Mutex::new(outcome), + calls: std::sync::atomic::AtomicUsize::new(0), + }) + } + fn calls(&self) -> usize { + self.calls.load(std::sync::atomic::Ordering::SeqCst) + } + } + impl Negotiator for CountingNegotiator { + fn negotiate(&self, _asset: &str, _offer: u64) -> NegotiationOutcome { + self.calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst); + self.outcome.lock().unwrap().clone() + } + } + + fn accepted() -> NegotiationOutcome { + NegotiationOutcome::Accepted { + price: "3000000".to_string(), + pay_token: "0xUSDC".to_string(), + } + } + + /// A negotiate intent: `capsule` is the budget key, `offer` the signed input_hash, and the + /// resource is the pay-scoped asset (the mandate boundary the envelope gate enforces). + fn negotiate_intent(capsule: &str, asset: &str, offer: &str) -> IntentDeclarationV1 { + let sk = ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()); + IntentDeclarationV1::issue( + &sk, + sk.verifying_key().to_bytes(), + "negotiate-intent-1", + capsule, + "runtime.negotiate", + offer, + &format!("{PAY_PREFIX}{asset}"), + // Read-authority: the dispatch gate only authorizes the fixed Action enum, and negotiate + // is a non-value-moving probe — it takes a `read` mandate on the pay resource (like + // market_quote). A made-up `negotiate` action would be denied at the gate. + "read", + "grant-1", + ) + } + + /// A budgeted meter + a counting seller wired into a negotiate registry. + fn negotiate_setup( + budget: u64, + outcome: NegotiationOutcome, + ) -> ( + MethodRegistryExecutor, + Arc, + Arc, + ) { + let meter = Arc::new(SpendMeter::new()); + meter.set_budget("vm-shopper", budget).unwrap(); + let seller = CountingNegotiator::new(outcome); + let exec = MethodRegistryExecutor::new().with_negotiation(meter.clone(), seller.clone()); + (exec, meter, seller) + } + + /// An accepted offer within the cap PERFORMS: it echoes the OFFER (declared == done ⇒ Matched, + /// so the receipt attests the agent offered exactly N), tags `action=negotiate`, settles no rail + /// (`rail_ref` none), and discloses the seller's terms on the explicit channel. + #[test] + fn negotiate_accept_performs_echoing_the_offer_and_discloses_terms() { + let (exec, meter, seller) = negotiate_setup(500, accepted()); + match exec.execute(&negotiate_intent("vm-shopper", "QmMovie", "5")) { + IntentExecution::Performed { + input_hash, + action, + rail_ref, + agent_visible_report, + .. + } => { + assert_eq!( + input_hash, "5", + "the receipt attests the exact offer — Matched" + ); + assert_eq!( + action, "read", + "a non-value-moving probe reconciles read (the gate authorizes only the fixed \ + Action enum) — the OFFER on input_hash is what makes it a proposal" + ); + assert!( + rail_ref.is_none(), + "negotiate settles nothing — no rail_ref" + ); + assert_eq!( + agent_visible_report.as_deref(), + Some("outcome=accept;price=3000000;tok=0xUSDC"), + "the seller's terms travel via the explicit disclosure channel" + ); + } + other => panic!("expected Performed, got {other:?}"), + } + assert_eq!(seller.calls(), 1, "the seller saw exactly one in-cap offer"); + // NON-VALUE-MOVING: negotiate only READS the cap — the balance is untouched. + assert_eq!( + meter.remaining("vm-shopper"), + 500, + "negotiate debits nothing — settlement stays runtime.pay" + ); + } + + /// RATCHET (the S50 pre-council bug): a faithful negotiate must reconcile Matched through the + /// REAL `reconcile`, which means the executor's returned `action` must EQUAL the declared action + /// AND be one the dispatch gate can authorize — the gate only speaks the fixed `Action` enum, so + /// a made-up `negotiate` action could never be granted by any token (the affordance would be + /// dead at the gate). This pins the returned action to a gate-legal, declaration-matching value. + #[test] + fn a_faithful_negotiate_returns_a_gate_legal_action_that_reconciles_matched() { + use elastos_runtime::capability::Action; + use std::str::FromStr; + let (exec, _meter, _seller) = negotiate_setup(500, accepted()); + let intent = negotiate_intent("vm-shopper", "QmMovie", "5"); + match exec.execute(&intent) { + IntentExecution::Performed { action, .. } => { + // Pins against the SAME parser the dispatch gate uses (Action's FromStr) — not a + // hand-copied action list — so a returned action no token could authorize fails CI. + assert!( + Action::from_str(&action).is_ok(), + "the returned action {action:?} must be a gate-authorizable Action enum value \ + — else no token could ever authorize a negotiate dispatch" + ); + assert_eq!( + action, intent.action, + "declared == done on the action ⇒ reconciles Matched, never Diverged" + ); + } + other => panic!("expected Performed, got {other:?}"), + } + } + + /// A counter PERFORMS too (the agent got actionable terms) — the report names the counter. + #[test] + fn negotiate_counter_performs_and_discloses_the_counter() { + let (exec, _meter, _seller) = negotiate_setup( + 500, + NegotiationOutcome::Countered { + price: "8000000".to_string(), + pay_token: "0xUSDC".to_string(), + }, + ); + match exec.execute(&negotiate_intent("vm-shopper", "QmMovie", "5")) { + IntentExecution::Performed { + agent_visible_report, + .. + } => assert_eq!( + agent_visible_report.as_deref(), + Some("outcome=counter;price=8000000;tok=0xUSDC") + ), + other => panic!("expected Performed, got {other:?}"), + } + } + + /// A rejection reaches no agreement ⇒ DECLINES (authorized_not_performed) with the seller's + /// bounded reason — an agreement is "performed" only when the seller returned terms. + #[test] + fn negotiate_rejection_declines_with_the_reason() { + let (exec, _meter, _seller) = + negotiate_setup(500, NegotiationOutcome::Rejected("sold out".to_string())); + match exec.execute(&negotiate_intent("vm-shopper", "QmMovie", "5")) { + IntentExecution::Declined { reason } => { + assert!(reason.contains("rejected"), "honest reason: {reason}"); + assert!( + reason.contains("sold out"), + "carries the seller's why: {reason}" + ); + } + other => panic!("expected Declined, got {other:?}"), + } + } + + /// THE PROVABLE PROPERTY: an offer above the mandate's un-spent cap is refused BEFORE the seller + /// ever sees it — an agent may not propose to commit its operator beyond granted authority. + #[test] + fn an_over_cap_offer_is_refused_before_the_seller() { + let (exec, meter, seller) = negotiate_setup(4, accepted()); + match exec.execute(&negotiate_intent("vm-shopper", "QmMovie", "5")) { + IntentExecution::Declined { reason } => { + assert!( + reason.contains("exceeds") && reason.contains("un-spent cap"), + "refused by the ceiling: {reason}" + ); + } + other => panic!("expected the cap ceiling to refuse, got {other:?}"), + } + assert_eq!( + seller.calls(), + 0, + "an over-cap offer NEVER reaches the seller — the commitment is bounded at the runtime" + ); + assert_eq!(meter.remaining("vm-shopper"), 4, "nothing was reserved"); + } + + /// An exactly-at-cap offer is allowed (the ceiling is inclusive), proving the boundary is off + /// by nothing. + #[test] + fn an_offer_exactly_at_the_cap_is_allowed() { + let (exec, _meter, seller) = negotiate_setup(5, accepted()); + assert!(matches!( + exec.execute(&negotiate_intent("vm-shopper", "QmMovie", "5")), + IntentExecution::Performed { .. } + )); + assert_eq!(seller.calls(), 1); + } + + /// An unprovisioned capsule has remaining == 0, so it cannot offer anything — fail-closed, + /// exactly as the buy's reservation refuses an unprovisioned capsule. + #[test] + fn an_unprovisioned_capsule_cannot_offer_anything() { + let (exec, _meter, seller) = negotiate_setup(500, accepted()); + // "vm-stranger" was never provisioned. + match exec.execute(&negotiate_intent("vm-stranger", "QmMovie", "1")) { + IntentExecution::Declined { reason } => { + assert!(reason.contains("un-spent cap"), "reason: {reason}") + } + other => panic!("expected Declined, got {other:?}"), + } + assert_eq!( + seller.calls(), + 0, + "an unprovisioned agent never reaches the seller" + ); + } + + /// The offer must be a CANONICAL positive integer of spend units — the same discipline the pay + /// amount is held to, so a Performed offer reconciles Matched (never Diverges on the echo). + #[test] + fn negotiate_offer_must_be_a_canonical_positive_integer() { + let (exec, _meter, seller) = negotiate_setup(500, accepted()); + for bad in ["0", "abc", "0200", "+5", " 5", "5 ", "-1", ""] { + match exec.execute(&negotiate_intent("vm-shopper", "QmMovie", bad)) { + IntentExecution::Declined { .. } => {} + other => panic!("offer {bad:?} must decline, got {other:?}"), + } + } + assert_eq!( + seller.calls(), + 0, + "a malformed offer never reaches the seller" + ); + } + + /// The pay namespace is the boundary: a non-pay resource declines before any seller call. + #[test] + fn negotiate_outside_the_pay_namespace_declines() { + let (exec, _meter, seller) = negotiate_setup(500, accepted()); + let sk = ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()); + let outside = IntentDeclarationV1::issue( + &sk, + sk.verifying_key().to_bytes(), + "negotiate-intent-2", + "vm-shopper", + "runtime.negotiate", + "5", + "elastos://runtime/state/secret-key", + "read", + "grant-1", + ); + match exec.execute(&outside) { + IntentExecution::Declined { reason } => { + assert!(reason.contains("resource must be"), "reason: {reason}") + } + other => panic!("expected Declined, got {other:?}"), + } + assert_eq!(seller.calls(), 0); + } + + /// A seller PANIC is caught and reads as no agreement — a hostile/buggy seam cannot take down + /// the dispatch worker, and (negotiate moving no money) no MONEY state is left in a bad state + /// (the only residual is a TTL-bounded quote-cache slot; council S50 guardian F5). + #[test] + fn a_seller_panic_is_no_agreement() { + struct PanicSeller; + impl Negotiator for PanicSeller { + fn negotiate(&self, _: &str, _: u64) -> NegotiationOutcome { + panic!("hostile seller"); + } + } + let meter = Arc::new(SpendMeter::new()); + meter.set_budget("vm-shopper", 500).unwrap(); + let exec = + MethodRegistryExecutor::new().with_negotiation(meter.clone(), Arc::new(PanicSeller)); + match exec.execute(&negotiate_intent("vm-shopper", "QmMovie", "5")) { + IntentExecution::Declined { reason } => { + assert!(reason.contains("panicked"), "reason: {reason}") + } + other => panic!("expected Declined on seller panic, got {other:?}"), + } + assert_eq!(meter.remaining("vm-shopper"), 500, "a panic moved no money"); + } + + /// Malformed seller terms (out of bound) reconcile as no agreement, never a fabricated match — + /// the seller-sourced report is held to the SAME bound the agent's own fields are. + #[test] + fn out_of_bound_seller_terms_reach_no_agreement() { + let huge = "x".repeat(300); + let (exec, _meter, _seller) = negotiate_setup( + 500, + NegotiationOutcome::Accepted { + price: huge, + pay_token: "0xUSDC".to_string(), + }, + ); + match exec.execute(&negotiate_intent("vm-shopper", "QmMovie", "5")) { + IntentExecution::Declined { reason } => { + assert!(reason.contains("malformed terms"), "reason: {reason}") + } + other => panic!("expected Declined on out-of-bound terms, got {other:?}"), + } + } + + /// RATCHET (council S50 guardian F1): a seller's REJECTION reason reaches the agent response and + /// the logs, so the executor must BOUND and SANITIZE it — a hostile seller cannot flood it or + /// inject control bytes (newlines/escapes). The prefix stays; the seller's bytes are clamped. + #[test] + fn a_hostile_seller_reject_reason_is_bounded_and_sanitized() { + let nasty = format!("line1\nline2\t\x1b[31mred\x07{}", "Z".repeat(500)); + let (exec, _meter, _seller) = negotiate_setup(500, NegotiationOutcome::Rejected(nasty)); + match exec.execute(&negotiate_intent("vm-shopper", "QmMovie", "5")) { + IntentExecution::Declined { reason } => { + assert!( + reason.starts_with("negotiation rejected by the seller: "), + "keeps the honest prefix: {reason}" + ); + assert!( + reason.len() <= "negotiation rejected by the seller: ".len() + 200, + "the seller's bytes are length-bounded: {} chars", + reason.len() + ); + assert!( + reason.chars().all(|c| c.is_ascii_graphic() || c == ' '), + "no control bytes reach the agent/logs: {reason:?}" + ); + } + other => panic!("expected Declined, got {other:?}"), + } + } +} diff --git a/elastos/crates/elastos-server/src/lib.rs b/elastos/crates/elastos-server/src/lib.rs index 9081381e..294c6b21 100644 --- a/elastos/crates/elastos-server/src/lib.rs +++ b/elastos/crates/elastos-server/src/lib.rs @@ -4,6 +4,7 @@ //! This crate provides the transport layer (HTTP) and binary entry point. //! The security-critical runtime logic lives in `elastos-runtime`. +pub mod agent_store; pub mod api; pub mod auth; pub mod binaries; @@ -14,20 +15,25 @@ pub mod carrier_service; pub mod content; pub mod crypto; pub mod documents; +pub mod drm_marketplace; pub mod egress_audit; pub mod fetcher; pub mod gateway_cmd; pub mod host_lock; pub mod init; pub mod inspect_provider; +pub mod intent_executor; pub mod ipfs; pub mod library; pub mod local_http; +pub mod market_quote; pub mod mcp_serve_cmd; +pub mod negotiation; pub mod net_validation; pub mod notifications; pub mod operator_control; pub mod ownership; +pub mod payment_ledger; pub mod provider_resource; pub mod room_service; pub mod runtime; diff --git a/elastos/crates/elastos-server/src/main.rs b/elastos/crates/elastos-server/src/main.rs index 1f527084..14775d0e 100755 --- a/elastos/crates/elastos-server/src/main.rs +++ b/elastos/crates/elastos-server/src/main.rs @@ -10,6 +10,7 @@ mod gateway_entry; mod home_cmd; mod identity_cmd; mod init_cmd; +mod mandate_cmd; mod node_cmd; mod publish; mod release_cmd; @@ -22,6 +23,7 @@ mod share_cmd; mod shares_cmd; mod site_cmd; mod trust_cmd; +mod verify_receipt_cmd; mod webspace_cmd; use clap::{Parser, Subcommand}; @@ -162,6 +164,26 @@ enum Commands { provenance: Option, }, + /// Mandate lifecycle: grant an agent scoped authority, revoke it, export its receipt + #[command(subcommand)] + Mandate(mandate_cmd::MandateCommand), + + /// Independently verify a portable mandate receipt (JSON) off-box + #[command(name = "verify-receipt")] + VerifyReceipt { + /// Path to the mandate receipt `.json` file + path: PathBuf, + + /// Pin the expected issuer: a `did:key:z...` or the 64-char hex of its ed25519 key. + /// Required to reach an AUTHENTIC verdict (exit 0); without it the check is structural only. + #[arg(long)] + signer: Option, + + /// Emit the full verdict as JSON instead of a human-readable report + #[arg(long)] + json: bool, + }, + /// Publish a capsule through the content availability provider Publish { /// Path to capsule directory @@ -1297,6 +1319,14 @@ async fn main() -> anyhow::Result<()> { return trust_cmd::run_verify(path, public_key, cid, provenance).await; } + Commands::Mandate(cmd) => { + return mandate_cmd::run_mandate(cmd).await; + } + + Commands::VerifyReceipt { path, signer, json } => { + return verify_receipt_cmd::run_verify_receipt(path, signer, json); + } + Commands::Publish { path } => { return capsule_publish_cmd::run_publish(path).await; } @@ -1734,7 +1764,13 @@ async fn serve_web_capsule( } else { std::process::Stdio::piped() }; - match tokio::process::Command::new(&shell_path) + let mut shell_cmd = tokio::process::Command::new(&shell_path); + // P16 (Sprint 46): the shell is a capsule spawn — strip the runtime-only secrets (rail + // bearer, broadcastable signed tx). ONE shared list: `provider::RUNTIME_ONLY_SECRETS`. + for secret in elastos_runtime::provider::RUNTIME_ONLY_SECRETS { + shell_cmd.env_remove(secret); + } + match shell_cmd .env("ELASTOS_API", &api_url) .env("ELASTOS_TOKEN", &shell_session.token) .env("ELASTOS_SHELL_MODE", &shell_mode) @@ -1823,6 +1859,7 @@ async fn serve_web_capsule( runtime, session_registry: infra.session_registry, capability_manager: infra.capability_manager, + standing_service: Some(infra.standing_service.clone()), pending_store: infra.pending_store, namespace_store: Some(infra.namespace_store), provider_registry: Some(infra.provider_registry), @@ -1838,6 +1875,7 @@ async fn serve_web_capsule( ready_tx: None, attach_secret: None, host_helpers: infra.host_helpers, + pay_rail: infra.pay_rail.clone(), }) .await; diff --git a/elastos/crates/elastos-server/src/mandate_cmd.rs b/elastos/crates/elastos-server/src/mandate_cmd.rs new file mode 100644 index 00000000..5caa5bb5 --- /dev/null +++ b/elastos/crates/elastos-server/src/mandate_cmd.rs @@ -0,0 +1,798 @@ +//! `elastos mandate` — the operator's mandate lifecycle: grant → revoke → prove. +//! +//! This is the Flint loop from the human side: hand an agent a SCOPED, EXPIRING, REVOCABLE +//! mandate instead of your keys (`grant`), kill it at any moment (`revoke`), and export the +//! portable, independently-verifiable proof of everything done under it (`receipt`, checked +//! off-box with `elastos verify-receipt`). +//! +//! The CLI holds NO authority of its own: every subcommand attaches to the RUNNING operator +//! runtime over the loopback control plane (the same attach-secret exchange the shell uses) and +//! calls the existing shell-scoped endpoints. The runtime remains the single writer of the audit +//! chain and the only holder of the signing key. + +use anyhow::{bail, Context, Result}; +use clap::Subcommand; + +use crate::runtime_control; +use elastos_runtime::capability::IntentDeclarationV1; +use elastos_server::intent_executor::AUDIT_CHAIN_RESOURCE; +use elastos_server::sources::default_data_dir; + +#[derive(Subcommand)] +pub(crate) enum MandateCommand { + /// Grant an agent a scoped, expiring, revocable mandate (mints a real capability token) + Grant { + /// The acting capsule identity the mandate authorizes (e.g. "vm-agent") + #[arg(long)] + capsule: String, + + /// The resource the mandate covers (e.g. "elastos://pay/vendor") + #[arg(long)] + resource: String, + + /// The action: read | write | execute | delete | message | admin + #[arg(long)] + action: String, + + /// Affordance method the agent may invoke under this mandate (repeatable, at least one) + #[arg(long = "method", required = true)] + methods: Vec, + + /// Time-to-live in seconds; omitted = until revoked + #[arg(long)] + ttl_secs: Option, + + /// Authorized agent's ed25519 public key (hex). When set, ONLY intents signed by this key + /// may act under the mandate — the audit attribution is the real agent. Recommended. + #[arg(long)] + agent_key: Option, + + /// Responsible entity: the operator/legal-entity DID accountable for the agent's acts under + /// this mandate (e.g. did:web:acme.example) — the EU-AI-Act liability binding, recorded in + /// the signed grant record and the portable receipt. Optional on the CLI; required on the + /// shell app. + #[arg(long)] + responsible_entity: Option, + }, + + /// Revoke a mandate NOW — durably attested on the audit chain, then enforced fail-closed + Revoke { + /// The mandate's token id (printed by `mandate grant`) + token_id: String, + }, + + /// Export the mandate's portable receipt (grant + every use/revoke) for off-box verification + Receipt { + /// The mandate's token id (printed by `mandate grant`) + token_id: String, + + /// Write the receipt JSON here instead of stdout + #[arg(short, long)] + output: Option, + }, + + /// List every standing mandate (live and revoked) with its scope and state + List, + + /// Run the whole loop once against the live runtime: grant → list → revoke → receipt → verify + Demo, + + /// The marketplace loop once, end to end (Sprint 38/39): provision a cap, grant the two + /// single-asset mandates (read quote + execute pay — one envelope carries one action), let + /// a scripted agent QUOTE the live terms, decide, and dispatch the buy — then watch it + /// resolve in the Mandates app's Marketplace panel. Requires a wired payment rail. + MarketDemo { + /// The DRM asset reference (KID / content id) — the payee of the pay resource + /// elastos://runtime/pay/ + asset: String, + + /// Spend units the mandate may spend on this buy (also the cap provisioned) + #[arg(long, default_value_t = 10)] + amount: u64, + }, +} + +/// Attach to the RUNNING operator runtime and return (api_url, shell_token). The mandate +/// lifecycle is a control-plane operation, so it requires the runtime that enforces it. +async fn attach_shell() -> Result<(String, String)> { + let data_dir = default_data_dir(); + let coords_path = runtime_control::runtime_coord_path(&data_dir); + let coords = runtime_control::read_operator_runtime_coords(&coords_path) + .await + .ok_or_else(|| anyhow::anyhow!(runtime_control::OPERATOR_RUNTIME_REQUIRED_MESSAGE))?; + if let Some(reason) = runtime_control::operator_runtime_staleness_reason(&coords).await? { + bail!("{reason}"); + } + let tokens = runtime_control::attach_to_runtime(&coords).await?; + Ok((coords.api_url.clone(), tokens.shell_token)) +} + +fn client() -> Result { + reqwest::Client::builder() + .timeout(std::time::Duration::from_secs(10)) + .build() + .context("building HTTP client") +} + +/// Surface a non-2xx response as the server's own error text (it is precise about why). +async fn error_for(resp: reqwest::Response, doing: &str) -> anyhow::Error { + let status = resp.status(); + let body = resp.text().await.unwrap_or_default(); + anyhow::anyhow!("{doing} failed ({status}): {body}") +} + +pub(crate) async fn run_mandate(cmd: MandateCommand) -> Result<()> { + match cmd { + MandateCommand::Grant { + capsule, + resource, + action, + methods, + ttl_secs, + agent_key, + responsible_entity, + } => { + let (api_url, shell_token) = attach_shell().await?; + let resp = client()? + .post(format!("{api_url}/api/standing-grants/issue")) + .header("Authorization", format!("Bearer {shell_token}")) + .json(&serde_json::json!({ + "capsule": capsule, + "resource": resource, + "action": action, + "methods": methods, + "ttl_secs": ttl_secs, + "agent_pubkey": agent_key, + "responsible_entity": responsible_entity, + })) + .send() + .await?; + if !resp.status().is_success() { + return Err(error_for(resp, "mandate grant").await); + } + let out: serde_json::Value = resp.json().await?; + let token_id = out + .get("token_id") + .or_else(|| out.get("grant_id")) + .and_then(|v| v.as_str()) + .context("runtime did not return a token id")? + .to_string(); + println!("Mandate granted."); + println!(" token id: {token_id}"); + println!(" capsule: {capsule}"); + println!(" scope: {action} on {resource}"); + println!(" methods: {}", methods.join(", ")); + match ttl_secs { + Some(secs) => println!(" expires: in {secs}s"), + None => println!(" expires: never (until revoked)"), + } + match &agent_key { + Some(k) => println!(" agent: bound to {k}"), + None => println!( + " agent: UNBOUND (any shell caller can act; pass --agent-key to bind)" + ), + } + println!("\nRevoke: elastos mandate revoke {token_id}"); + println!("Prove: elastos mandate receipt {token_id} -o receipt.json"); + Ok(()) + } + + MandateCommand::Revoke { token_id } => { + let (api_url, shell_token) = attach_shell().await?; + let resp = client()? + .post(format!("{api_url}/api/standing-grants/revoke")) + .header("Authorization", format!("Bearer {shell_token}")) + .json(&serde_json::json!({ "grant_id": token_id })) + .send() + .await?; + if !resp.status().is_success() { + return Err(error_for(resp, "mandate revoke").await); + } + let out: serde_json::Value = resp.json().await?; + let envelope_was_live = out + .get("revoked") + .and_then(|v| v.as_bool()) + .unwrap_or(false); + // The durable CapabilityRevoke is attested by the runtime BEFORE this returns success + // (emit-before-mutate), so reaching here means the revoke record is on the chain and + // the token is dead in the runtime's persistent revocation store. + println!( + "Token {token_id} revoked: signed CapabilityRevoke attested on the audit chain." + ); + if envelope_was_live { + println!("Its live standing mandate is killed; further dispatch is denied."); + } else { + // The kill switch's one job is "after this, the mandate is dead" — a mistyped + // (but well-formed) id would revoke a token that never existed while the REAL + // mandate stays live. Make that impossible to miss. + eprintln!( + "WARNING: no LIVE standing mandate matched this id. If you expected to kill a \ + live mandate, re-check the token id (`elastos mandate grant` printed it) — a \ + mistyped id attests a revoke for a token that never existed while the real \ + mandate STAYS LIVE. (This is expected if the mandate was already revoked or \ + the token was granted outside the standing-mandate flow.)" + ); + } + println!("Prove it: elastos mandate receipt {token_id} -o receipt.json"); + Ok(()) + } + + MandateCommand::Receipt { token_id, output } => { + let (api_url, shell_token) = attach_shell().await?; + let resp = client()? + .get(format!("{api_url}/api/mandate/{token_id}/receipt")) + .header("Authorization", format!("Bearer {shell_token}")) + .send() + .await?; + if !resp.status().is_success() { + return Err(error_for(resp, "mandate receipt export").await); + } + let receipt: serde_json::Value = resp.json().await?; + let pretty = serde_json::to_string_pretty(&receipt)?; + let signer = receipt + .get("signer_public_key_hex") + .and_then(|v| v.as_str()) + .unwrap_or("") + .to_string(); + match output { + Some(path) => { + std::fs::write(&path, &pretty) + .with_context(|| format!("writing {}", path.display()))?; + println!("Receipt written to {}", path.display()); + // Deliberately NOT inlining the receipt's own embedded signer into the verify + // command: pinning the key a document carries about itself is circular — a + // wholesale forgery would "authenticate" against its own key. The pin must + // come from the verifier's out-of-band trust in the issuing runtime. + println!(" receipt's embedded signer (informational): {signer}"); + println!( + "Verify off-box, pinning the issuer key YOU trust out-of-band:\n \ + elastos verify-receipt {} --signer ", + path.display() + ); + } + None => println!("{pretty}"), + } + Ok(()) + } + + MandateCommand::List => { + let (api_url, shell_token) = attach_shell().await?; + let list = fetch_mandate_list(&api_url, &shell_token).await?; + print_mandate_list(&list); + Ok(()) + } + + MandateCommand::Demo => run_demo().await, + MandateCommand::MarketDemo { asset, amount } => run_market_demo(&asset, amount).await, + } +} + +async fn fetch_mandate_list(api_url: &str, shell_token: &str) -> Result { + let resp = client()? + .get(format!("{api_url}/api/standing-grants")) + .header("Authorization", format!("Bearer {shell_token}")) + .send() + .await?; + if !resp.status().is_success() { + return Err(error_for(resp, "mandate list").await); + } + Ok(resp.json().await?) +} + +fn print_mandate_list(list: &serde_json::Value) { + let mandates = list + .get("mandates") + .and_then(|m| m.as_array()) + .cloned() + .unwrap_or_default(); + if mandates.is_empty() { + println!("No standing mandates this runtime lifetime."); + return; + } + println!("{} standing mandate(s):", mandates.len()); + for m in &mandates { + let s = |k: &str| m.get(k).and_then(|v| v.as_str()).unwrap_or("?").to_string(); + let active = m.get("active").and_then(|v| v.as_bool()).unwrap_or(false); + let revoked = m.get("revoked").and_then(|v| v.as_bool()).unwrap_or(false); + let state = if active { + "LIVE" + } else if revoked { + "REVOKED" + } else { + "EXPIRED" + }; + let methods = m + .get("methods") + .and_then(|v| v.as_array()) + .map(|a| { + a.iter() + .filter_map(|x| x.as_str()) + .collect::>() + .join(", ") + }) + .unwrap_or_default(); + println!("\n [{}] {}", state, s("token_id")); + println!(" capsule: {}", s("capsule")); + println!(" scope: {} on {}", s("action"), s("resource")); + println!(" methods: {methods}"); + } +} + +/// The whole Flint loop, once, against the live runtime — nothing simulated, nothing fabricated: +/// a REAL mandate is granted (and left revoked at the end), every record lands on the REAL audit +/// chain, and the receipt is verified in-process with the signer pinned over the AUTHENTICATED +/// loopback control plane (the operator's trust in their own runtime — not the receipt vouching +/// for itself). +/// The marketplace loop, end to end, against the live runtime (Sprint 38): cap → pay-mandate → +/// the agent's signed buy intent → the ledger records the honest outcome. Everything here is the +/// EXISTING machinery (`/api/spend-budgets`, the shared mint path, the standing-grant dispatch); +/// this process merely plays the agent (it generates the key in-memory, as `demo` does). The +/// mandate is revoked at the end — the demo leaves no live authority behind; the buy's ledger +/// record REMAINS (that is the point: watch it in the Mandates app's Marketplace panel). +async fn run_market_demo(asset: &str, amount: u64) -> Result<()> { + let asset = asset.trim(); + if asset.is_empty() { + bail!("the asset reference (KID / content id) must be non-empty"); + } + let (api_url, shell_token) = attach_shell().await?; + let http = client()?; + let capsule = "vm-market-demo-agent"; + let resource = format!("elastos://runtime/pay/{asset}"); + + println!("── 1. CAP — provision {amount} spend units for {capsule} ──"); + let resp = http + .post(format!("{api_url}/api/spend-budgets")) + .header("Authorization", format!("Bearer {shell_token}")) + .json(&serde_json::json!({ "capsule": capsule, "limit": amount })) + .send() + .await?; + if !resp.status().is_success() { + let err = error_for(resp, "cap provisioning").await; + eprintln!( + "(a wired payment rail + durable stores are required — see \ + docs/DRM_MARKETPLACE_RAIL.md for the env)" + ); + return Err(err); + } + println!("cap set: {capsule} may spend up to {amount} units\n"); + + println!("── 2. GRANT — TWO mandates on one resource, bound to one agent key ──"); + println!("(one envelope carries ONE action: quoting is a `read`, paying is an `execute` —"); + println!(" so the agent holds a read quote-mandate AND an execute pay-mandate, same asset)"); + let agent = ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()); + let agent_pub_hex = hex::encode(agent.verifying_key().to_bytes()); + // Issue one grant; on a 2xx whose token id cannot be read, warn LOUDLY (mirror `demo`) — + // a live authority may exist that we cannot target for cleanup. + let issue = |action: &'static str, method: &'static str| { + let http = http.clone(); + let api_url = api_url.clone(); + let shell_token = shell_token.clone(); + let resource = resource.clone(); + let agent_pub_hex = agent_pub_hex.clone(); + async move { + let resp = http + .post(format!("{api_url}/api/standing-grants/issue")) + .header("Authorization", format!("Bearer {shell_token}")) + .json(&serde_json::json!({ + "capsule": "vm-market-demo-agent", + "resource": resource, + "action": action, + "methods": [method], + "ttl_secs": 3600, + "agent_pubkey": agent_pub_hex, + })) + .send() + .await?; + if !resp.status().is_success() { + return Err(error_for(resp, "market-demo grant").await); + } + let token_id = resp.json::().await.ok().and_then(|out| { + out.get("token_id") + .or_else(|| out.get("grant_id")) + .and_then(|v| v.as_str()) + .map(str::to_string) + }); + match token_id { + Some(t) => Ok(t), + None => { + eprintln!( + "WARNING: a {action}/{method} mandate was granted but its token id \ + could not be read — a live 1h mandate for vm-market-demo-agent may \ + exist. Check `elastos mandate list` and revoke it." + ); + bail!("grant response did not carry a token id"); + } + } + } + }; + let quote_token = issue("read", "runtime.market_quote").await?; + let pay_token = issue("execute", "runtime.pay").await?; + println!( + "granted quote-mandate {quote_token} (read) + pay-mandate {pay_token} (execute): agent \ + {} on {resource}, 1h TTL\n", + &agent_pub_hex[..16] + ); + + // From here live authorities exist — revoke BOTH on ANY exit. + let result = market_demo_buy( + &http, + &api_url, + &shell_token, + &agent, + "e_token, + &pay_token, + asset, + amount, + ) + .await; + println!("── 5. REVOKE — the demo leaves no live authority behind ──"); + for token_id in ["e_token, &pay_token] { + let cleanup = http + .post(format!("{api_url}/api/standing-grants/revoke")) + .header("Authorization", format!("Bearer {shell_token}")) + .json(&serde_json::json!({ "grant_id": token_id })) + .send() + .await; + match cleanup { + Ok(r) if r.status().is_success() => println!("revoked {token_id}"), + _ => eprintln!( + "CLEANUP REVOKE FAILED — a live 1h mandate remains: run \ + `elastos mandate revoke {token_id}`" + ), + } + } + // Clear the demo cap too — a cap alone authorizes nothing (spending needs a live mandate + + // a signed intent), but the demo should not leave standing money-state behind either. + let cap_cleanup = http + .delete(format!("{api_url}/api/spend-budgets/{capsule}")) + .header("Authorization", format!("Bearer {shell_token}")) + .send() + .await; + match cap_cleanup { + Ok(r) if r.status().is_success() => println!("cleared the {capsule} spend cap\n"), + _ => println!( + "(the {amount}-unit spend cap for {capsule} remains provisioned — a cap alone \ + authorizes nothing; clear it from the Money panel or the API)\n" + ), + } + result?; + println!( + "Open the Mandates app → Marketplace panel to watch the buy: a broadcast reads \ + \"awaiting chain confirmation\" until the confirmation scheduler (or a manual \ + reconcile) records the chain's verdict; a refusal reads refused with the reservation \ + refunded. The row IS the enforcing ledger's record." + ); + Ok(()) +} + +/// The agent's leg of the market demo (Sprint 39: quote-THEN-buy — the first decision-making +/// agent act): read the live terms under the mandate, decide, and only then dispatch the buy. +#[allow(clippy::too_many_arguments)] +async fn market_demo_buy( + http: &reqwest::Client, + api_url: &str, + shell_token: &str, + agent: &ed25519_dalek::SigningKey, + quote_token: &str, + pay_token: &str, + asset: &str, + amount: u64, +) -> Result<()> { + println!("── 3. QUOTE — the agent reads the live terms under its READ quote-mandate ──"); + let quote_intent = IntentDeclarationV1::issue( + agent, + agent.verifying_key().to_bytes(), + &format!("market-demo-quote-{quote_token}"), + "vm-market-demo-agent", + "runtime.market_quote", + "", // discovery mode: no expected terms + &format!("elastos://runtime/pay/{asset}"), + "read", + quote_token, + ); + let resp = http + .post(format!("{api_url}/api/standing-grants/dispatch")) + .header("Authorization", format!("Bearer {shell_token}")) + .json("e_intent) + .send() + .await?; + if !resp.status().is_success() { + return Err(error_for(resp, "market-demo quote").await); + } + let out: serde_json::Value = resp.json().await?; + let quote_outcome = out + .get("outcome") + .and_then(|v| v.as_str()) + .unwrap_or("unknown"); + match out.get("report").and_then(|v| v.as_str()) { + Some(terms) if quote_outcome == "performed" => { + println!("the agent read the terms: {terms}"); + println!( + "decision: proceed — the runtime's price gate is the real ceiling (a buy above \ + the mandate's cap x spend-unit is refused before broadcast)\n" + ); + } + _ => { + let reason = out.get("reason").and_then(|v| v.as_str()).unwrap_or("-"); + println!("quote did not return terms: outcome={quote_outcome} ({reason})"); + println!( + "decision: NOT buying — an agent that cannot price an asset does not spend on it\n" + ); + bail!("market-demo stopped at the quote (no terms) — nothing was bought"); + } + } + + println!("── 4. BUY — the agent signs the pay intent under its EXECUTE pay-mandate ──"); + let intent = IntentDeclarationV1::issue( + agent, + agent.verifying_key().to_bytes(), + &format!("market-demo-buy-{pay_token}"), + "vm-market-demo-agent", + "runtime.pay", + &amount.to_string(), // the amount rides in the signed input_hash (canonical decimal) + &format!("elastos://runtime/pay/{asset}"), + "execute", + pay_token, + ); + let resp = http + .post(format!("{api_url}/api/standing-grants/dispatch")) + .header("Authorization", format!("Bearer {shell_token}")) + .json(&intent) + .send() + .await?; + if !resp.status().is_success() { + return Err(error_for(resp, "market-demo dispatch").await); + } + let out: serde_json::Value = resp.json().await?; + let outcome = out + .get("outcome") + .and_then(|v| v.as_str()) + .unwrap_or("unknown"); + let reason = out.get("reason").and_then(|v| v.as_str()).unwrap_or("-"); + println!("dispatched runtime.pay {amount} → {asset}: outcome={outcome} ({reason})"); + println!( + "(honest wording: a DRM buy is `authorized_not_performed` even on a SUCCESSFUL broadcast \ + — performed is reserved for chain-confirmed truth)\n" + ); + Ok(()) +} + +/// The whole Flint loop once against the live runtime: grant → list → the agent's real act → +/// revoke → the same act denied → receipt exported and verified. +async fn run_demo() -> Result<()> { + let (api_url, shell_token) = attach_shell().await?; + let http = client()?; + + // The AGENT holds its OWN key. In production the agent generates and keeps this; the operator + // only ever learns its PUBLIC half and binds the mandate to it — never the agent's keys, and + // never the operator's. Here the demo stands in for the agent and generates an ephemeral key. + let agent = ed25519_dalek::SigningKey::generate(&mut rand::thread_rng()); + let agent_pub_hex = hex::encode(agent.verifying_key().to_bytes()); + + println!( + "(demo note: the ACTS below are real, but this process plays the agent — it generates the\n \ + agent key in-memory. In production the agent holds its own key; the operator binds only the\n \ + public half.)\n" + ); + println!("── 1. GRANT — a scoped, expiring, revocable mandate bound to ONE agent key ──"); + let resp = http + .post(format!("{api_url}/api/standing-grants/issue")) + .header("Authorization", format!("Bearer {shell_token}")) + .json(&serde_json::json!({ + "capsule": "vm-demo-agent", + "resource": AUDIT_CHAIN_RESOURCE, + "action": "read", + "methods": ["runtime.audit_verify"], + "ttl_secs": 3600, + "agent_pubkey": agent_pub_hex, + })) + .send() + .await?; + if !resp.status().is_success() { + return Err(error_for(resp, "demo grant").await); + } + // The grant SUCCEEDED (2xx) — from here a live mandate may exist. If we cannot read its token + // id, we cannot target a cleanup revoke, so warn LOUDLY (the mandate is TTL-bounded and findable + // via `mandate list`) rather than return silently as though nothing was granted. + let token_id = resp.json::().await.ok().and_then(|out| { + out.get("token_id") + .or_else(|| out.get("grant_id")) + .and_then(|v| v.as_str()) + .map(str::to_string) + }); + let token_id = match token_id { + Some(t) => t, + None => { + eprintln!( + "WARNING: the mandate was granted but its token id could not be read — a live \ + mandate for vm-demo-agent may exist. Check `elastos mandate list` and revoke it." + ); + bail!("grant response did not carry a token id"); + } + }; + println!("granted mandate {token_id}: agent {} may runtime.audit_verify (read {AUDIT_CHAIN_RESOURCE}), 1h TTL\n", &agent_pub_hex[..16]); + + // From here a REAL 1h authority exists. If any later step fails, the mandate must not be + // stranded live — attempt the revoke as cleanup before surfacing the error. + match demo_after_grant(&http, &api_url, &shell_token, &token_id, &agent).await { + Ok(()) => Ok(()), + Err(e) => { + eprintln!( + "demo step failed; revoking the demo mandate so no live authority is left behind…" + ); + let cleanup = http + .post(format!("{api_url}/api/standing-grants/revoke")) + .header("Authorization", format!("Bearer {shell_token}")) + .json(&serde_json::json!({ "grant_id": token_id })) + .send() + .await; + match cleanup { + Ok(r) if r.status().is_success() => eprintln!("cleanup revoke succeeded."), + _ => eprintln!( + "CLEANUP REVOKE FAILED — a live 1h demo mandate remains: run \ + `elastos mandate revoke {token_id}`" + ), + } + Err(e) + } + } +} + +/// The agent signs an `audit_verify` intent under its own key and dispatches it. Returns the +/// dispatch outcome ("performed" / "denied" / …). +/// Returns `(outcome, reason)` — `reason` is the fail-closed denial reason (snake_case) when denied. +async fn agent_dispatch( + http: &reqwest::Client, + api_url: &str, + shell_token: &str, + agent: &ed25519_dalek::SigningKey, + token_id: &str, + intent_id: &str, +) -> Result<(String, Option)> { + let intent = IntentDeclarationV1::issue( + agent, + agent.verifying_key().to_bytes(), + intent_id, + "vm-demo-agent", + "runtime.audit_verify", + "", // no arguments + AUDIT_CHAIN_RESOURCE, + "read", + token_id, + ); + let resp = http + .post(format!("{api_url}/api/standing-grants/dispatch")) + .header("Authorization", format!("Bearer {shell_token}")) + .json(&intent) + .send() + .await?; + if !resp.status().is_success() { + return Err(error_for(resp, "agent dispatch").await); + } + let out: serde_json::Value = resp.json().await?; + let outcome = out + .get("outcome") + .and_then(|v| v.as_str()) + .unwrap_or("unknown") + .to_string(); + let reason = out + .get("reason") + .and_then(|v| v.as_str()) + .map(str::to_string); + Ok((outcome, reason)) +} + +async fn demo_after_grant( + http: &reqwest::Client, + api_url: &str, + shell_token: &str, + token_id: &str, + agent: &ed25519_dalek::SigningKey, +) -> Result<()> { + println!("── 2. LIST — the mandate is LIVE on the operator surface ──"); + let list = fetch_mandate_list(api_url, shell_token).await?; + print_mandate_list(&list); + let pinned_signer = list + .get("signer_public_key_hex") + .and_then(|v| v.as_str()) + .context("runtime did not report its audit signer (memory-only log?)")? + .to_string(); + + // Intent ids are unique per demo RUN (suffixed with this run's fresh token id) so re-running the + // demo against the same long-lived runtime does not collide with its per-lifetime replay guard. + let act1_id = format!("demo-act-1-{token_id}"); + let act2_id = format!("demo-act-2-{token_id}"); + + println!("\n── 3. ACT — the agent signs an intent and the runtime REALLY performs it ──"); + let (outcome, _) = + agent_dispatch(http, api_url, shell_token, agent, token_id, &act1_id).await?; + println!("agent dispatched runtime.audit_verify → {outcome}"); + if outcome != "performed" { + bail!("expected the agent's authorized act to be performed, got {outcome:?}"); + } + println!("(the runtime re-verified its own tamper-evident audit chain — a real, side-effect-free act)\n"); + + println!("── 4. REVOKE — the kill switch, durably attested before it mutates ──"); + let resp = http + .post(format!("{api_url}/api/standing-grants/revoke")) + .header("Authorization", format!("Bearer {shell_token}")) + .json(&serde_json::json!({ "grant_id": token_id })) + .send() + .await?; + if !resp.status().is_success() { + return Err(error_for(resp, "demo revoke").await); + } + println!("revoked {token_id}: signed CapabilityRevoke on the chain, envelope killed\n"); + + println!("── 5. ACT AGAIN — the SAME agent, now denied (the kill switch has teeth) ──"); + let (after, reason) = + agent_dispatch(http, api_url, shell_token, agent, token_id, &act2_id).await?; + println!( + "agent re-dispatched after revoke → {after} ({})", + reason.as_deref().unwrap_or("-") + ); + // Must be denied SPECIFICALLY because the mandate was revoked — not some incidental denial. + if after != "denied" || reason.as_deref() != Some("revoked") { + bail!("expected the post-revoke act to be denied with reason=revoked, got {after:?}/{reason:?}"); + } + println!(); + + println!("── 6. RECEIPT — the portable, set-bound proof of the whole mandate ──"); + let resp = http + .get(format!("{api_url}/api/mandate/{token_id}/receipt")) + .header("Authorization", format!("Bearer {shell_token}")) + .send() + .await?; + if !resp.status().is_success() { + return Err(error_for(resp, "demo receipt").await); + } + let receipt: elastos_runtime::primitives::MandateReceipt = resp.json().await?; + // Narrate the ACTUAL records the receipt carries (the token-keyed use records are best-effort, + // so report what is really there rather than asserting a fixed trail). + let trail: Vec<&str> = receipt + .records + .iter() + .map(|r| match &r.event { + elastos_runtime::primitives::AuditEvent::CapabilityGrant { .. } => "grant", + elastos_runtime::primitives::AuditEvent::CapabilityUse { success: true, .. } => { + "performed-read" + } + elastos_runtime::primitives::AuditEvent::CapabilityUse { success: false, .. } => { + "denied-attempt" + } + elastos_runtime::primitives::AuditEvent::CapabilityRevoke { .. } => "revoke", + _ => "other", + }) + .collect(); + println!( + "exported: {} records [{}], signed by {}\n", + receipt.records.len(), + trail.join(" → "), + receipt.signer_public_key_hex + ); + + println!("── 7. VERIFY — the receipt against the pin from your runtime's control plane ──"); + // Honest scope: within one demo run the pin and the receipt come from the SAME runtime over + // the SAME channel, so this demonstrates the pinning MECHANISM (and self-consistency), not + // independent third-party verification — a counterparty runs verify-receipt on their own box + // with a pin they obtained out-of-band. + let verdict = + elastos_runtime::primitives::verify_mandate_receipt(&receipt, Some(&pinned_signer)); + println!(" structurally valid: {}", verdict.structurally_valid); + println!(" set binding: {}", verdict.set_binding_ok); + println!(" scope rule: {}", verdict.scope_ok); + println!(" pin matched: {}", verdict.authenticated); + println!(" (pin provenance: this runtime's control plane — self-asserted; a counterparty"); + println!(" pins the key they trust out-of-band and verifies on their own box)"); + if !verdict.authenticated { + bail!("demo receipt failed verification: {verdict:?}"); + } + println!( + "\nThe loop is closed: a scoped mandate GRANTED to one agent key, a real act PERFORMED" + ); + println!( + "under it, the kill switch REVOKED it, a post-revoke attempt DENIED, and the whole thing" + ); + println!("PROVEN — hand receipt + `elastos verify-receipt` to anyone; no runtime, no trust in this box."); + Ok(()) +} diff --git a/elastos/crates/elastos-server/src/market_quote.rs b/elastos/crates/elastos-server/src/market_quote.rs new file mode 100644 index 00000000..cefdf0be --- /dev/null +++ b/elastos/crates/elastos-server/src/market_quote.rs @@ -0,0 +1,279 @@ +//! The ONE market-quote spine (Sprint 39): a single-flight, TTL-cached, read-only view of a DRM +//! listing's live terms, shared by BOTH quote consumers — the Mandates app's Marketplace panel +//! (Sprint 38) and the agent-facing `runtime.market_quote` affordance (Sprint 39). One cache, one +//! claim discipline, one fan-out bound: however many surfaces ask, an asset costs at most one +//! live chain read per TTL window. +//! +//! READ-ONLY BY CONSTRUCTION: the only chain call behind this module is +//! [`buy_authority::quote_buy`](crate::api::buy_authority::quote_buy) — no keys, no broadcast +//! (P3). CI injects a [`MarketQuoter`] mock; production uses [`LiveMarketQuoter`]. + +use std::sync::Arc; + +/// How long one asset's quote is served from cache before a re-read. Together with the in-flight +/// sentinel this makes the fan-out bound literal: at most one LIVE chain read per asset per +/// window, however many concurrent consumers race (a miss claims the slot under the lock before +/// any read starts; later misses see the claim and wait for the cache). +pub const MARKET_QUOTE_TTL_SECS: u64 = 30; + +/// One asset's quote outcome: either the live terms or a length-bounded error string (rendered +/// via textContent only on the panel; surfaced as a decline reason to an agent). +#[derive(Clone, serde::Serialize)] +pub struct MarketQuote { + #[serde(skip_serializing_if = "Option::is_none")] + pub price: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub pay_token: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub supply: Option, + /// Length-bounded read failure — the asset stays listed/answerable, honestly unquoted. + #[serde(skip_serializing_if = "Option::is_none")] + pub error: Option, +} + +impl MarketQuote { + /// The canonical one-line terms encoding for a SUCCESSFUL quote — + /// `price=

;tok=;supply=` — the string an attested quote intent declares and the + /// executor echoes (declared-vs-done). `None` when this quote is an error outcome. + pub fn canonical_terms(&self) -> Option { + match (&self.price, &self.pay_token, self.supply) { + (Some(price), Some(tok), Some(supply)) if self.error.is_none() => { + // The same `;`/`=` stripping the DRM rail_ref uses, so segments can't be forged. + let clean = |s: &str| s.replace([';', '='], ""); + Some(format!( + "price={};tok={};supply={supply}", + clean(price), + clean(tok) + )) + } + _ => None, + } + } +} + +/// One cache slot: `quote: None` is the IN-FLIGHT sentinel — a consumer has claimed this asset's +/// chain read and not yet finished. The sentinel expires by the same TTL (a crashed fetch can +/// never wedge an asset), and concurrent consumers that see a fresh sentinel get "in progress" +/// instead of spawning a duplicate read (single-flight). +#[derive(Clone)] +pub struct MarketQuoteSlot { + pub quoted_at: u64, + pub quote: Option, +} + +/// The per-process quote cache: asset → slot. Pruned by TTL on every claim pass, so it stays +/// bounded by the recently-asked asset set. Lives on [`PayRail`](crate::api::server::PayRail) — +/// the same one-per-process home as the meter and ledger — so the panel and the affordance share +/// it same-Arc by construction. +pub type MarketQuoteCache = + Arc>>; + +/// What one single-flight claim pass says about one asset. +pub enum CachedQuote { + /// A fresh quote is cached — served free, no chain read. + Fresh(MarketQuote), + /// Another consumer's read is in flight — do not duplicate it; retry shortly. + InFlight, + /// THIS consumer claimed the read (the sentinel is now in place): perform it, then [`fill`]. + Claimed, + /// No cached quote and the caller declined to claim (its fresh-read budget is spent). + NotClaimed, +} + +/// The single-flight claim pass for ONE asset, under the cache lock: prune expired slots, serve a +/// fresh quote, respect an in-flight claim, or (when `may_claim`) claim the read by inserting the +/// sentinel BEFORE any chain call starts — the step that makes "one live read per asset per +/// window" literal under concurrency. +pub fn claim_or_serve( + cache: &MarketQuoteCache, + asset: &str, + now: u64, + may_claim: bool, +) -> CachedQuote { + let mut cache = match cache.lock() { + Ok(c) => c, + Err(poisoned) => poisoned.into_inner(), + }; + let fresh = |slot: &MarketQuoteSlot| now.saturating_sub(slot.quoted_at) < MARKET_QUOTE_TTL_SECS; + match cache.get(asset) { + Some(slot) if fresh(slot) => match &slot.quote { + Some(quote) => CachedQuote::Fresh(quote.clone()), + None => CachedQuote::InFlight, + }, + // Absent OR stale (an expired quote/sentinel reads as absent — freshness is checked + // inline so callers prune ONCE per pass, not per asset; council S39 fold). + _ if may_claim => { + cache.insert( + asset.to_string(), + MarketQuoteSlot { + quoted_at: now, + quote: None, + }, + ); + CachedQuote::Claimed + } + _ => CachedQuote::NotClaimed, + } +} + +/// Drop every slot past the TTL — the size bound. Call ONCE per batch pass (the panel view) or +/// per single-asset ask; `claim_or_serve` itself never scans the whole map. +pub fn prune(cache: &MarketQuoteCache, now: u64) { + if let Ok(mut cache) = cache.lock() { + cache.retain(|_, slot| now.saturating_sub(slot.quoted_at) < MARKET_QUOTE_TTL_SECS); + } +} + +/// Publish a completed read into the cache, stamped at COMPLETION time (a slow fetch must not be +/// served as fresh for a full TTL past its actual read time). +pub fn fill(cache: &MarketQuoteCache, asset: &str, quote: MarketQuote, completed_at: u64) { + if let Ok(mut cache) = cache.lock() { + cache.insert( + asset.to_string(), + MarketQuoteSlot { + quoted_at: completed_at, + quote: Some(quote), + }, + ); + } +} + +/// The read seam: CI injects a mock; production injects [`LiveMarketQuoter`], whose only call is +/// the existing read-only `quote_buy` path (no new chain code). +pub trait MarketQuoter: Send + Sync { + fn quote(&self, asset: &str) -> Result; +} + +/// Production quoter — `buy_authority::quote_buy` with an empty target (the same call the panel's +/// batch pass makes). +pub struct LiveMarketQuoter; +impl MarketQuoter for LiveMarketQuoter { + fn quote(&self, asset: &str) -> Result { + crate::api::buy_authority::quote_buy( + asset, + &crate::api::buy_authority::BuyTarget::default(), + ) + } +} + +/// Convert one quoter result into the cacheable outcome, bounding the error string (a chain error +/// must not balloon a panel payload or a decline reason). +pub fn quote_outcome(result: Result) -> MarketQuote { + match result { + Ok(q) => MarketQuote { + price: Some(q.price), + pay_token: Some(q.pay_token), + supply: Some(q.supply), + error: None, + }, + Err(e) => MarketQuote { + price: None, + pay_token: None, + supply: None, + error: Some(e.chars().take(200).collect()), + }, + } +} + +/// Another consumer's read of the same asset is in flight — retry shortly (bounded wait is the +/// CALLER's policy; this module never sleeps). A named unit-error so the contract is visible at +/// call sites (clippy `result_unit_err`, S48 gate-truth fold). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct ReadInFlight; + +/// One asset's quote through the shared spine, blocking (the caller runs on the blocking pool): +/// serve fresh, refuse to duplicate an in-flight read, or claim-read-fill. +pub fn quote_single_flight( + cache: &MarketQuoteCache, + quoter: &dyn MarketQuoter, + asset: &str, + now: u64, +) -> Result { + prune(cache, now); // single-asset ask: one bounded prune keeps the cache size-bounded + match claim_or_serve(cache, asset, now, true) { + CachedQuote::Fresh(quote) => Ok(quote), + CachedQuote::InFlight => Err(ReadInFlight), + CachedQuote::Claimed => { + let quote = quote_outcome(quoter.quote(asset)); + fill(cache, asset, quote.clone(), now_unix()); + Ok(quote) + } + // Unreachable with may_claim=true, but fail SAFE (treat as in-flight) if it ever is. + CachedQuote::NotClaimed => Err(ReadInFlight), + } +} + +/// Seconds since the unix epoch (the cache's clock). +pub fn now_unix() -> u64 { + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .map(|d| d.as_secs()) + .unwrap_or(0) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn canonical_terms_strip_separator_bytes_and_require_success() { + let ok = MarketQuote { + price: Some("50;00=00".to_string()), + pay_token: Some("0xUSDC".to_string()), + supply: Some(3), + error: None, + }; + assert_eq!( + ok.canonical_terms().unwrap(), + "price=500000;tok=0xUSDC;supply=3", + "separator bytes in chain-sourced fields cannot forge extra segments" + ); + let err = MarketQuote { + price: None, + pay_token: None, + supply: None, + error: Some("nope".to_string()), + }; + assert!( + err.canonical_terms().is_none(), + "an error outcome has no terms" + ); + } + + #[test] + fn single_flight_claims_once_and_serves_the_cache() { + struct CountingQuoter(std::sync::atomic::AtomicUsize); + impl MarketQuoter for CountingQuoter { + fn quote(&self, _: &str) -> Result { + self.0.fetch_add(1, std::sync::atomic::Ordering::SeqCst); + Ok(crate::api::buy_authority::BuyQuote { + price: "5".to_string(), + pay_token: "native".to_string(), + supply: 1, + }) + } + } + let cache: MarketQuoteCache = Arc::default(); + let quoter = CountingQuoter(std::sync::atomic::AtomicUsize::new(0)); + let now = now_unix(); + let first = quote_single_flight(&cache, "er, "QmA", now).expect("claim + read"); + assert_eq!(first.price.as_deref(), Some("5")); + let second = quote_single_flight(&cache, "er, "QmA", now).expect("cache hit"); + assert_eq!(second.price.as_deref(), Some("5")); + assert_eq!( + quoter.0.load(std::sync::atomic::Ordering::SeqCst), + 1, + "one live read per asset per window — the second ask is a cache hit" + ); + // A fresh in-flight sentinel refuses a duplicate read rather than racing it. + claim_or_serve(&cache, "QmB", now, true); // claims QmB, never filled + assert!(matches!( + claim_or_serve(&cache, "QmB", now, true), + CachedQuote::InFlight + )); + assert!( + quote_single_flight(&cache, "er, "QmB", now).is_err(), + "a concurrent claim is respected — no duplicate chain read" + ); + } +} diff --git a/elastos/crates/elastos-server/src/negotiation.rs b/elastos/crates/elastos-server/src/negotiation.rs new file mode 100644 index 00000000..8dd7df00 --- /dev/null +++ b/elastos/crates/elastos-server/src/negotiation.rs @@ -0,0 +1,336 @@ +//! The negotiate seam (Sprint 50 — Track D3): the middle leg of the shop loop +//! (quote → **negotiate** → pay). An agent under a pay-mandate makes a BOUNDED OFFER for a +//! mandate-scoped asset; the SELLER decides. The runtime supplies the AGENT side of the protocol — +//! a mandate-capped, receipted way to make an offer — and injects a [`Negotiator`] for the SELLER +//! side, exactly as the quote spine injects a [`MarketQuoter`](crate::market_quote::MarketQuoter). +//! +//! WHAT THE RUNTIME OWNS (in the `runtime.negotiate` executor, not here): the offer is a canonical +//! positive integer of SPEND UNITS, and it is refused BEFORE reaching the seller if it exceeds the +//! mandate's UN-SPENT cap (`SpendMeter::remaining`). That is the one provable property this leg +//! adds: **an agent can never propose to commit its operator beyond the granted, un-spent +//! authority** — the same ceiling the buy enforces, applied to the OFFER. +//! +//! WHAT THIS SEAM OWNS: the seller's accept/counter/reject decision, and any unit math the +//! seller's own price domain needs. The runtime passes the offer as an opaque spend-unit integer +//! and RELAYS the seller's answer; it does not interpret the seller's numbers or attest them (a +//! counterparty's word is not something the runtime can verify — see the receipt note below). +//! +//! NOT VALUE-MOVING BY CONSTRUCTION: negotiate produces AGREED/COUNTER TERMS, never a charge. It +//! touches neither the ledger nor the meter's balance (it only READS `remaining`). Settlement stays +//! `runtime.pay`, which re-checks the cap and runs the whole two-generals custody path. So there is +//! no two-generals problem here: nothing is broadcast, nothing is reserved, no money can move. +//! +//! THE RECEIPT records the ACT — "under this mandate, the agent offered N spend units for asset X" +//! (N is signed, and N ≤ cap is proven) — NOT the seller's disposition. The accept-vs-counter +//! outcome and the seller's price ride the response's agent-visible channel, exactly as a quote's +//! terms do (ephemeral market data, not something the runtime signs on a counterparty's behalf). + +use std::sync::Arc; + +/// The seller's answer to one bounded offer. `price`/`pay_token` are the seller's own price domain +/// (rail units for the listing seller) — DISPLAY data the agent reads to decide its next move +/// (pay the counter, re-offer, or walk); the runtime never interprets them numerically. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum NegotiationOutcome { + /// The seller ACCEPTS at `price` in `pay_token`. A fair seller accepts AT its ask, never above + /// the offer — the agent pays `price`, not whatever it over-offered. + Accepted { price: String, pay_token: String }, + /// The seller COUNTERS with `price` in `pay_token` (its firm terms). The agent may pay it, + /// re-negotiate, or walk — each a fresh receipted dispatch. + Countered { price: String, pay_token: String }, + /// No terms — a reason string. The negotiation act performed no agreement (⇒ the executor + /// DECLINES, `authorized_not_performed`), exactly as an unreadable quote does. The reason is + /// bounded AND sanitized by the executor before it reaches the agent (`with_negotiation`), so a + /// hostile seller cannot flood or inject control bytes through it — the type does not bound it. + Rejected(String), +} + +impl NegotiationOutcome { + /// The canonical one-line report the agent receives for a SUCCESSFUL negotiation (accept or + /// counter): `outcome=;price=

;tok=`. `None` for a rejection (no terms). + /// Separator bytes in seller-sourced fields are stripped, the same defense the DRM `rail_ref` + /// and [`MarketQuote::canonical_terms`](crate::market_quote::MarketQuote::canonical_terms) use, + /// so a hostile seller cannot forge extra segments into the signed-adjacent report. + pub fn agent_report(&self) -> Option { + let clean = |s: &str| s.replace([';', '='], ""); + match self { + NegotiationOutcome::Accepted { price, pay_token } => Some(format!( + "outcome=accept;price={};tok={}", + clean(price), + clean(pay_token) + )), + NegotiationOutcome::Countered { price, pay_token } => Some(format!( + "outcome=counter;price={};tok={}", + clean(price), + clean(pay_token) + )), + NegotiationOutcome::Rejected(_) => None, + } + } +} + +/// The seller seam. CI injects a scripted seller; the DRM deployment injects [`ListingNegotiator`]. +/// `offer` is in SPEND UNITS (the mandate's cap domain); the implementor maps it into its own price +/// domain if it needs to. Blocking is fine (the caller runs on the blocking pool) but the +/// implementor MUST bound any I/O it does — the listing seller inherits the quote spine's chain-read +/// deadline (S40) for exactly this reason. +/// +/// NORMATIVE — implementations MUST be observationally READ-ONLY (council S50 guardian F3): the +/// offer must not LEAVE the deployment's own read path (no outbound transmission to a counterparty, +/// no state write, no value move). `runtime.negotiate` is classified `read` and non-value-moving on +/// that basis, so a read mandate authorizes it; an outbound-negotiating seller (one that emits the +/// offer to a remote party in the operator's name) would make it side-effecting and MUST NOT be +/// wired here until the affordance's action is reclassified accordingly. The shipped +/// [`ListingNegotiator`] is a pure local read (chain-read spine + compare), honoring this. +pub trait Negotiator: Send + Sync { + fn negotiate(&self, asset: &str, offer: u64) -> NegotiationOutcome; +} + +/// The production seller for the DRM marketplace: a FIXED-PRICE ("take it or leave it") seller +/// backed by the SAME read-only quote spine the Marketplace panel and `runtime.market_quote` read +/// (one live chain read per asset per TTL window, no keys, no broadcast — P3). It does NOT haggle +/// below its ask, because on-chain DRM listings are fixed-price: a deployment with a discountable +/// seller wires a different [`Negotiator`]. The VALUE this leg delivers is the AGENT-side +/// mandate-bound offer primitive and the loop closure (quote → negotiate → pay), which holds +/// whatever the seller's sophistication. +/// +/// THE DECISION, through the SHARED `authorize_amount_against_listing` the buy gate also calls — +/// so it is the buy gate's conversion BY CONSTRUCTION (one function, not a synced copy): +/// 1. Read the live listing terms. Unreadable / sold out / no listing ⇒ [`Rejected`] (no agreement +/// on an unreadable listing — the honest counterpart of the buy quote failing NotCharged). +/// 2. PAY-TOKEN GUARD (council S36 F3, mirrored): if the listing quotes a different pay-token than +/// the deployment declared `spend_unit` FOR, the offer and the ask are in incomparable +/// denominations ⇒ [`Rejected`]. Never accept across token denominations. +/// 3. `authorized = offer × spend_unit` (checked; overflow ⇒ [`Rejected`]) — the offer in the +/// listing's own base-units, the identical `amount × spend_unit` the buy price gate computes. +/// 4. `authorized ≥ price` ⇒ [`Accepted`] at the LISTING price (never above the offer). Else +/// ⇒ [`Countered`] with the listing price (the seller's firm ask). +/// +/// HONEST BOUND: the terms are as of the spine's LAST read (≤ `MARKET_QUOTE_TTL_SECS` old, shared +/// with the panel/quote fan-out bound); a listing that changes inside the cache window is caught on +/// the next re-read. A settlement STILL re-quotes live and aborts on drift (the buy gate binds the +/// quote), so a stale accept here can never make the agent overpay at pay time. +pub struct ListingNegotiator { + cache: crate::market_quote::MarketQuoteCache, + quoter: Arc, + /// Pay-token smallest-units per spend unit — the SAME mapping the DRM buy gate is wired with. + spend_unit: u128, + /// The pay-token that `spend_unit` denominates, if the deployment declared one (live Chain + /// mode always does; dev/chain-mock may omit it, matching the buy gate). + expected_pay_token: Option, +} + +impl ListingNegotiator { + pub fn new( + cache: crate::market_quote::MarketQuoteCache, + quoter: Arc, + spend_unit: u128, + expected_pay_token: Option, + ) -> Self { + Self { + cache, + quoter, + // Mirror the buy gate's `spend_unit.max(1)` floor: a zero mapping would make every + // offer authorize nothing (0 base-units) and counter forever — the buy provider clamps + // to 1 for the same reason, so the two conversions stay identical. + spend_unit: spend_unit.max(1), + expected_pay_token, + } + } +} + +impl Negotiator for ListingNegotiator { + fn negotiate(&self, asset: &str, offer: u64) -> NegotiationOutcome { + // Read the live listing through the shared spine (bounded, single-flight, TTL-cached). + let quote = match crate::market_quote::quote_single_flight( + &self.cache, + self.quoter.as_ref(), + asset, + crate::market_quote::now_unix(), + ) { + Ok(q) => q, + Err(crate::market_quote::ReadInFlight) => { + return NegotiationOutcome::Rejected( + "a listing read for this asset is already in flight — retry shortly" + .to_string(), + ); + } + }; + let (Some(price_str), Some(pay_token)) = (quote.price.clone(), quote.pay_token.clone()) + else { + return NegotiationOutcome::Rejected(format!( + "the listing could not be read: {}", + quote.error.as_deref().unwrap_or("no terms returned") + )); + }; + // THE conversion — token guard, price parse, `offer × spend_unit`, cover boundary — is the + // SHARED `authorize_amount_against_listing` the DRM buy gate also calls (council S50 + // guardian F2): one implementation, so a negotiate "accept" corresponds EXACTLY to what the + // buy gate will pass. The seller formats its own accept/counter/reject from the result. + match crate::drm_marketplace::authorize_amount_against_listing( + offer, + self.spend_unit, + self.expected_pay_token.as_deref(), + &price_str, + &pay_token, + ) { + Err(crate::drm_marketplace::ListingAuthzError::TokenMismatch { listing, declared }) => { + NegotiationOutcome::Rejected(format!( + "the listing quotes pay-token {listing} but the declared spend-unit mapping is \ + for {declared} — the offer cannot be compared across token denominations" + )) + } + Err(crate::drm_marketplace::ListingAuthzError::UnparseablePrice(p)) => { + NegotiationOutcome::Rejected(format!( + "the listing price is not a parseable amount ({p})" + )) + } + Err(crate::drm_marketplace::ListingAuthzError::Overflow) => NegotiationOutcome::Rejected( + "offer × spend_unit overflowed — refusing to negotiate an unrepresentable amount" + .to_string(), + ), + // The offer covers the ask — accept AT the ask (never take more than listed). + Ok(authz) if authz.covers() => NegotiationOutcome::Accepted { + price: authz.price.to_string(), + pay_token, + }, + // Below ask — the fixed-price seller counters with its firm listing price. + Ok(authz) => NegotiationOutcome::Countered { + price: authz.price.to_string(), + pay_token, + }, + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::api::buy_authority::BuyQuote; + + /// A quoter that returns a fixed listing (or an error) — the seam the ListingNegotiator reads. + struct FixedQuoter(Result); + impl crate::market_quote::MarketQuoter for FixedQuoter { + fn quote(&self, _: &str) -> Result { + self.0.clone() + } + } + + fn negotiator_over( + listing: Result, + spend_unit: u128, + pay_token: Option<&str>, + ) -> ListingNegotiator { + ListingNegotiator::new( + Arc::default(), + Arc::new(FixedQuoter(listing)), + spend_unit, + pay_token.map(|s| s.to_string()), + ) + } + + fn listing(price: &str, tok: &str) -> Result { + Ok(BuyQuote { + price: price.to_string(), + pay_token: tok.to_string(), + supply: 1, + }) + } + + #[test] + fn an_offer_that_covers_the_ask_is_accepted_at_the_ask_not_above() { + // spend_unit 1_000_000 (USDC 6dp): offer 5 ⇒ authorized 5_000_000 ≥ price 3_000_000. + let neg = negotiator_over(listing("3000000", "0xUSDC"), 1_000_000, Some("0xUSDC")); + let out = neg.negotiate("QmA", 5); + assert_eq!( + out, + NegotiationOutcome::Accepted { + price: "3000000".to_string(), // AT the ask, not the over-offer + pay_token: "0xUSDC".to_string(), + } + ); + assert_eq!( + out.agent_report().unwrap(), + "outcome=accept;price=3000000;tok=0xUSDC" + ); + } + + #[test] + fn an_offer_below_the_ask_is_countered_with_the_firm_listing_price() { + // offer 2 ⇒ authorized 2_000_000 < price 3_000_000 ⇒ counter at 3_000_000. + let neg = negotiator_over(listing("3000000", "0xUSDC"), 1_000_000, Some("0xUSDC")); + let out = neg.negotiate("QmA", 2); + assert_eq!( + out, + NegotiationOutcome::Countered { + price: "3000000".to_string(), + pay_token: "0xUSDC".to_string(), + } + ); + assert_eq!( + out.agent_report().unwrap(), + "outcome=counter;price=3000000;tok=0xUSDC" + ); + } + + #[test] + fn a_listing_in_a_different_pay_token_is_rejected_never_accepted_across_denominations() { + let neg = negotiator_over(listing("1", "0xWETH"), 1_000_000, Some("0xUSDC")); + assert!(matches!( + neg.negotiate("QmA", 100), + NegotiationOutcome::Rejected(why) if why.contains("across token denominations") + )); + } + + #[test] + fn an_unreadable_listing_yields_no_agreement() { + let neg = negotiator_over(Err("chain unreachable".to_string()), 1, None); + assert!(matches!( + neg.negotiate("QmA", 100), + NegotiationOutcome::Rejected(why) if why.contains("could not be read") + )); + } + + #[test] + fn an_unparseable_listing_price_is_rejected_fail_closed() { + let neg = negotiator_over(listing("not-a-number", "native"), 1, None); + assert!(matches!( + neg.negotiate("QmA", 100), + NegotiationOutcome::Rejected(why) if why.contains("not a parseable amount") + )); + } + + #[test] + fn the_conversion_overflow_refuses_rather_than_wraps() { + // offer × spend_unit overflows u128 ⇒ refuse (never wrap into a bogus "authorized"). + let neg = negotiator_over(listing("1", "native"), u128::MAX, Some("native")); + assert!(matches!( + neg.negotiate("QmA", u64::MAX), + NegotiationOutcome::Rejected(why) if why.contains("overflow") + )); + } + + #[test] + fn a_zero_spend_unit_is_floored_to_one_like_the_buy_gate() { + // spend_unit 0 would authorize nothing; the floor to 1 keeps it identical to the buy gate. + let neg = negotiator_over(listing("5", "native"), 0, Some("native")); + // offer 5 × floored-unit 1 = 5 ≥ price 5 ⇒ accept. + assert!(matches!( + neg.negotiate("QmA", 5), + NegotiationOutcome::Accepted { .. } + )); + } + + #[test] + fn separator_bytes_in_seller_terms_cannot_forge_report_segments() { + let out = NegotiationOutcome::Accepted { + price: "3;tok=evil".to_string(), + pay_token: "0x=;USDC".to_string(), + }; + assert_eq!( + out.agent_report().unwrap(), + "outcome=accept;price=3tokevil;tok=0xUSDC", + "a hostile seller cannot inject extra ;/= segments into the report" + ); + } +} diff --git a/elastos/crates/elastos-server/src/notifications.rs b/elastos/crates/elastos-server/src/notifications.rs index b8351fa8..83361aaa 100644 --- a/elastos/crates/elastos-server/src/notifications.rs +++ b/elastos/crates/elastos-server/src/notifications.rs @@ -345,6 +345,128 @@ pub fn dismiss_external_http_request(data_dir: &Path, request_id: &str) -> anyho dismiss(data_dir, &external_http_request_notification_id(request_id)) } +/// Notification kind for an agent act performed under a standing mandate (`runtime.notify`). +pub const AGENT_ACT_KIND: &str = "agent_mandate_act"; + +/// Agent-act rows are self-reclaiming: they carry a TTL so `load_summary`'s existing prune +/// removes them, and are hard-capped so an agent flooding distinct intents under ONE mandate +/// cannot grow the operator's Inbox store without bound (council F1 — the events store three +/// functions down is capped the same way; this closes the omitted twin). Newest are kept. +const AGENT_ACT_TTL_SECS: u64 = 7 * 24 * 60 * 60; // 7 days +const AGENT_ACT_MAX_ROWS: usize = 256; + +/// Deliver an agent's mandate-gated message into the operator's Inbox — the REAL side effect +/// behind the `runtime.notify` affordance. The row's id is keyed on the intent id, so the SAME +/// intent can never produce two rows (the dispatch replay guard already refuses a re-POST; this +/// is the belt to that suspender). Content is a FIXED honest shape built from the signed +/// declaration's own fields, and the caller (`runtime.notify` executor) bounds `intent_id` and +/// `input_hash` to operator-safe shapes BEFORE calling — so nothing free-text reaches the operator +/// surface (council F1). Severity `Info`: an authorized act is news, not an alarm. +pub fn post_agent_act_notification( + data_dir: &Path, + intent_id: &str, + capsule: &str, + topic: &str, + input_hash: &str, + grant_id: &str, +) -> anyhow::Result<()> { + let id = format!("agent-act:{intent_id}"); + let path = notifications_path(data_dir)?; + let mut store = read_json_or_default::(&path)?; + if store.schema.trim().is_empty() { + store.schema = NOTIFICATIONS_SCHEMA.to_string(); + } + let created_at = SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_secs()) + .unwrap_or(0); + // Idempotent ONLY on a LIVE prior row (council F4): a re-dispatch that finds a still-visible + // delivery is an honest Ok; but a dismissed/expired row is NOT an operator-visible delivery, so + // treating it as one would report Performed for a message the operator will never see. Under + // that (cross-store divergence) case we fall through and re-deliver, so the report stays honest. + if let Some(existing) = store.entries.iter().find(|entry| entry.id == id) { + let live = !existing.dismissed + && existing + .expires_at + .is_none_or(|expires_at| expires_at > created_at); + if live { + return Ok(()); + } + store.entries.retain(|entry| entry.id != id); + } + let title = format!("Agent message: {topic}"); + let input_note = if input_hash.is_empty() { + "no declared inputs".to_string() + } else { + format!("input hash {input_hash}") + }; + let body = format!( + "{capsule} acted under mandate {grant_id} (intent {intent_id}, {input_note}). \ + Open Mandates for the receipt." + ); + let record = NotificationEntryRecord { + id: id.clone(), + source_app: "mandates".to_string(), + kind: AGENT_ACT_KIND.to_string(), + title: title.clone(), + body: body.clone(), + action_ref: None, + created_at, + // Self-reclaiming TTL so the operator's store never accretes agent-act rows forever. + expires_at: Some(created_at.saturating_add(AGENT_ACT_TTL_SECS)), + severity: NotificationSeverity::Info, + read: false, + acted: false, + dismissed: false, + }; + store.entries.push(record); + // Hard cap the agent-act rows (newest kept), so a flood of distinct intents under one mandate + // cannot grow the store without bound between prunes — the room/external-http rows are left + // untouched (their own lifecycle governs them). + let agent_act_count = store + .entries + .iter() + .filter(|e| e.kind == AGENT_ACT_KIND) + .count(); + if agent_act_count > AGENT_ACT_MAX_ROWS { + let mut to_drop = agent_act_count - AGENT_ACT_MAX_ROWS; + store.entries.retain(|e| { + if to_drop > 0 && e.kind == AGENT_ACT_KIND { + to_drop -= 1; + false + } else { + true + } + }); + } + // Durable-before-event (council F3): the STORE write is the real side effect — land it first + // and let ITS result decide Performed/Declined. Its failure returns Err (⇒ the executor + // Declines, honestly). A failed store write never leaves a ghost "appeared" event for a row the + // operator never saw. + write_json_atomic(&path, &store)?; + // The event log is a secondary audit breadcrumb (no production reader today); a hiccup here must + // NOT flip a delivery that DID land into a Declined under-claim. Best-effort, logged not fatal. + if let Err(e) = record_event( + data_dir, + NotificationEventRecord { + id: format!("appeared:{id}"), + notification_id: id, + source_app: "mandates".to_string(), + title, + body, + action_ref: None, + created_at, + disposition: NotificationEventDisposition::Appeared, + resolution: None, + }, + ) { + tracing::warn!( + "agent-act notification delivered but its appeared-event was not recorded: {e}" + ); + } + Ok(()) +} + fn external_http_request_notification_id(request_id: &str) -> String { format!("external-http-request:{request_id}") } diff --git a/elastos/crates/elastos-server/src/payment_ledger.rs b/elastos/crates/elastos-server/src/payment_ledger.rs new file mode 100644 index 00000000..d26e8b32 --- /dev/null +++ b/elastos/crates/elastos-server/src/payment_ledger.rs @@ -0,0 +1,1147 @@ +//! The payment ledger — a durable record of every rail attempt, and the operator's reconciliation +//! surface for INDETERMINATE outcomes (Sprint 30, council S29 RT-F4/G-F7). +//! +//! WHY THIS EXISTS: the two-generals handling in the pay affordance keeps the cap reservation when +//! a rail outcome is indeterminate (timeout/5xx/panic — the charge may have posted). That is the +//! fail-closed direction, but it strands headroom the operator can only safely restore by asking +//! the RAIL what actually happened (a blind cap raise can authorize real spend beyond the original +//! intent). This ledger makes that reconciliation possible without reading logs or deriving keys +//! from the chain: every rail attempt lands here with its idempotency key, and a PENDING entry can +//! be RESOLVED exactly once — "not charged" refunds the reservation, "charged" confirms the spend. +//! +//! It also durably custodies the RAIL REFERENCE for every performed payment (council S29 G-F7) — +//! the audit bridge from a Performed receipt to the rail's transaction — until a receipt field +//! carries it (tracked follow-on). +//! +//! HONEST BOUNDS (council S30): +//! - CUSTODY IS "EVERY RAIL ATTEMPT THE PROCESS LIVED TO RECORD", not literally every attempt: a +//! crash between the persisted reservation and the rail verdict leaves a durable reservation +//! with NO ledger entry (the S29 orphaned-reservation window) — recovery there is still +//! deriving `flint-` from the on-chain declaration. PENDING custody is +//! guaranteed-or-stated (an unrecordable pending is named in the decline reason); TERMINAL +//! records (performed / not-charged) are best-effort — a failed write drops the rail reference +//! to the runtime log only. +//! - THE LEDGER GATES MONEY IN THE RELEASE DIRECTION (council S30 G-F1): it never gates the +//! CHARGE path (a payment completes with its fail-closed semantics whether or not its record +//! lands), but a resolved record's (capsule, amount) is the INPUT to a reconciliation refund — +//! so this file is money-trusted core on release and carries the meter's protections: same +//! snapshot discipline, same single-opener flock, same data_dir trust class (the snapshot is +//! not self-authenticating; a data_dir writer already owns the stronger attack on the meter +//! file itself). +//! - This ledger is OPERATIONAL custody, not the signed chain: entries are not signed; the signed +//! record of the act remains the intent declaration + reconciliation on the audit chain, and a +//! RESOLUTION is attested there (`Custom` event, emitted by the handler). +//! - BOUNDED, per capsule and globally: terminal entries are evicted oldest-first past the global +//! cap; PENDING entries are never evicted (they are the reconciliation obligations); a capsule +//! at its own pending cap — or a global map full of pendings — refuses NEW pending entries +//! (recorded=false ⇒ stated in the reason). The per-capsule bound (council S30 RT-F3) confines +//! the blinding to the misbehaving capsule: one agent flooding indeterminates cannot push a +//! VICTIM capsule's obligations out of the work list. A full pending set also stops best-effort +//! terminal custody — the stated consequence of the bound. + +use std::collections::HashMap; +use std::path::PathBuf; +use std::sync::RwLock; + +/// Where one rail attempt stands. `Pending` is the only non-terminal state. +#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum PaymentStatus { + /// The rail confirmed the charge (2xx) — `rail_ref` carries its reference. + Performed, + /// The rail provably did not charge — the reservation was refunded by the pay path. + NotCharged, + /// INDETERMINATE — the charge may have posted; the reservation is held. Awaiting resolution. + Pending, + /// Operator resolved against the rail: the charge DID post. Spend stands. + ResolvedCharged, + /// Operator resolved against the rail: the charge did NOT post. The reservation was refunded + /// (or the refund's failure surfaced loudly — see the reconcile handler). + ResolvedNotCharged, +} + +impl PaymentStatus { + fn is_terminal(self) -> bool { + !matches!(self, PaymentStatus::Pending) + } + + /// Whether an entry may move money (or already has) — the states the idempotency guard relies + /// on to refuse a re-charge (council S35 guardian F3 / red-team F1). These MUST NOT be evicted: + /// evicting a `Performed`/`ResolvedCharged` key would let a cross-window re-dispatch of the + /// same signed intent find no entry and buy again. Only the provably-nothing-moved terminals + /// (`NotCharged`/`ResolvedNotCharged`) are safe to evict. + fn is_money_bearing(self) -> bool { + matches!( + self, + PaymentStatus::Pending | PaymentStatus::Performed | PaymentStatus::ResolvedCharged + ) + } +} + +/// The result of [`PaymentLedger::begin_attempt`] — the durable custody handle the pay path takes +/// BEFORE it broadcasts (council S35 red-team F1), so a re-dispatch can never find "no entry" for a +/// buy whose money moved. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum BeginAttempt { + /// A `Pending` placeholder is durably recorded; the caller may now move money and then + /// [`finalize`](PaymentLedger::finalize) the outcome. + Started, + /// The key already carries a money-bearing entry (a concurrent dispatch beat this one). The + /// caller must NOT move money again — decline idempotently and refund THIS attempt's reservation. + AlreadyActive(PaymentStatus), + /// The ledger could not durably custody the attempt (per-capsule pending cap, ledger full of + /// money-bearing entries, or a persist failure). The caller MUST NOT broadcast — refund and + /// decline fail-closed, so money never moves into an unrecordable state. + CapacityRefused, +} + +/// Which rail a payment record belongs to — a STRUCTURED discriminator (Sprint 44) so the DRM +/// confirmation reconciler polls ONLY records it owns, instead of sniffing the `rail_note` for a +/// `drm:tx=` prefix (council S35 red-team F5 / MKT-DRM 2d: a hostile HTTP endpoint could craft an +/// Indeterminate body starting `drm:tx=` and get its pending polled/resolved by the DRM driver). +/// The tag is set from the paying [`PaymentProvider`] at record creation, so it is NOT +/// rail-controlled text. `Unknown` is the back-compat default for pre-S44 records on disk (and for +/// providers that don't declare a rail); the reconciler treats an `Unknown` record's `drm:tx=` note +/// as the bounded legacy fallback, but a positively-tagged `Http` record is NEVER polled by the DRM +/// driver regardless of its note. +/// FORWARD-COMPAT (council S44 red-team F4): this enum is deliberately NOT `#[serde(other)]` — an +/// unrecognized `rail` string in a snapshot fails the load fail-CLOSED (the ledger refuses to boot +/// on a corrupt/unknown record, consistent with `PaymentStatus` and the module's "corrupt snapshot +/// ⇒ REFUSE" posture), rather than silently degrading an unknown rail to `Unknown`+note-fallback. +/// The consequence: adding a variant is a FORWARD-INCOMPATIBLE ledger change — an OLDER runtime +/// reading a snapshot that a NEWER runtime wrote with the new variant will refuse to load until the +/// downgrade is reversed. Adding a rail variant therefore requires a coordinated upgrade (or a +/// snapshot version bump), NOT a silent rollout. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum PaymentRail { + /// Untagged: a pre-S44 record, or a provider that declares no rail. Reconcilers fall back to + /// the note heuristic for these (bounded, drains as legacy records resolve). + #[default] + Unknown, + /// The HTTP payment rail ([`HttpPaymentProvider`](crate::intent_executor::HttpPaymentProvider)). + Http, + /// The DRM on-chain marketplace rail (`drm_marketplace::DrmMarketplaceProvider`). + Drm, + /// The ERC-20 checkout rail (`api::erc20_checkout::Erc20CheckoutProvider`, Sprint 48) — the + /// second chain-settled vertical; its pendings carry `erc20:tx=` notes and are reconciled by + /// the same chain-settled spine as `Drm`. NOTE: per the forward-compat contract above, adding + /// this variant means a pre-S48 runtime refuses to load a snapshot containing an `erc20` + /// record — a coordinated upgrade, as documented. + Erc20, +} + +/// One rail attempt. `rail_note` is the sanitized (printable, bounded) rail body/reference. +#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] +pub struct PaymentRecord { + /// The signature-derived idempotency key — the rail-side lookup handle. Ledger key. + pub idempotency_key: String, + pub capsule: String, + pub payee: String, + pub amount: u64, + pub status: PaymentStatus, + /// Sanitized rail reference/body head (printable ASCII, ≤256) — empty when none. + pub rail_note: String, + /// Monotonic insertion sequence (this ledger's own counter) — the eviction order. + pub seq: u64, + /// For `ResolvedNotCharged`: whether the refund was durably applied to the meter (council S30 + /// G-F3/RT-F2). `false` on a resolved-not-charged entry is the FORENSIC marker for a crash (or + /// persist failure) between resolution and refund: the refund was never applied, the cap + /// remains debited, and the recovery lever is raising the limit. Absent/false on all other + /// statuses. + #[serde(default)] + pub refund_applied: bool, + /// The mandate token (`standing_grant_id`) this payment was made under (Sprint 35). Lets a + /// reconciliation bind the confirmed settlement back onto the mandate's receipt (a token-keyed + /// `CapabilityUse`). `None` for a payment recorded without a bound mandate, and for every + /// pre-S35 record on disk. BACK-COMPAT: appended last with `#[serde(default, + /// skip_serializing_if = "Option::is_none")]`, so a pre-S35 ledger snapshot round-trips + /// unchanged. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub token_id: Option, + /// The rail this record belongs to (Sprint 44). Set from the paying provider at creation, so + /// the DRM reconciler can identify its records structurally, not by sniffing `rail_note`. + /// BACK-COMPAT: `#[serde(default)]` ⇒ a pre-S44 snapshot round-trips as `Unknown`; the field is + /// always serialized (a plain enum, not skipped) so a re-persisted legacy record gains the tag. + #[serde(default)] + pub rail: PaymentRail, +} + +#[derive(serde::Serialize, serde::Deserialize)] +struct LedgerSnapshotV1 { + version: u32, + next_seq: u64, + records: Vec, +} + +const LEDGER_SNAPSHOT_VERSION: u32 = 1; +/// Total record cap; terminal entries beyond it are evicted oldest-first. +const LEDGER_CAP: usize = 4096; +/// Per-capsule bound on PENDING entries (council S30 RT-F3): one capsule flooding indeterminates +/// cannot exhaust the global map and blind a VICTIM capsule's reconciliation obligations. +const PENDING_PER_CAPSULE_CAP: usize = 256; + +/// Hold rail-controlled bytes to a printable discipline BEFORE they enter any reason, record, or +/// surface (council S29 RT-F7): printable ASCII only (control chars — incl. CR/LF/ESC, killing +/// log/ANSI injection — and non-ASCII dropped), ≤256. NOT HTML-escaped: `<>"'&` survive as inert +/// ASCII — any HTML renderer of a `rail_note` MUST escape at render (council S30 F8). +pub fn sanitize_rail_note(raw: &str) -> String { + raw.chars() + .filter(|c| (' '..='~').contains(c)) + .take(256) + .collect() +} + +/// Why a resolution was refused — structured so AUTOMATION can distinguish retry from terminal +/// (council S30 G-F2: one 409 string made a transient persist failure read as "already resolved", +/// abandoning a live refund obligation). +#[derive(Debug, PartialEq, Eq)] +pub enum ResolveError { + /// No entry for this key (404): never recorded, or an unrecorded pending — reconcile via the + /// operator's out-of-band levers, not this endpoint. + NotFound, + /// The entry is terminal (409): the payment already resolved (or never needed to) — a payment + /// resolves exactly once, retrying is wrong. + NotPending(PaymentStatus), + /// The resolution could not be durably recorded and was ROLLED BACK — the entry is STILL + /// pending and the obligation still live (503): RETRY. + Persist, + /// Lock poisoned (503): retry. + Lock, +} + +impl std::fmt::Display for ResolveError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + ResolveError::NotFound => write!(f, "no ledger entry for this idempotency key"), + ResolveError::NotPending(st) => write!( + f, + "entry is not pending (status {st:?}) — a payment resolves exactly once" + ), + ResolveError::Persist => write!( + f, + "resolution could not be durably recorded; the entry stays pending (rolled back) — retry" + ), + ResolveError::Lock => write!(f, "ledger lock poisoned — retry"), + } + } +} + +/// Admission control for a NEW ledger key — the single home of the bounding invariant, shared by +/// [`PaymentLedger::record_with_token`] and [`PaymentLedger::begin_attempt`]. Returns `false` when +/// the entry cannot be admitted. +/// +/// Two rules, in order: +/// 1. Per-capsule pending bound (council S30 RT-F3): a capsule at its pending cap refuses NEW +/// pending entries — the blinding is confined to the misbehaving capsule, never a victim's +/// work list. +/// 2. Global bound: evict the oldest EVICTABLE entry — a provably-nothing-moved terminal +/// (`NotCharged`/`ResolvedNotCharged`) ONLY. Money-bearing keys (`Pending`/`Performed`/ +/// `ResolvedCharged`) are NEVER evicted (council S35 guardian F3): evicting a charged key +/// would let a cross-window re-dispatch find no entry and re-buy. A cap full of money-bearing +/// entries REFUSES the new insert fail-closed (the pay path then refuses to broadcast) rather +/// than forgetting a key idempotency depends on. +fn admit_new_key( + records: &mut HashMap, + capsule: &str, + pending: bool, +) -> bool { + if pending + && records + .values() + .filter(|r| r.status == PaymentStatus::Pending && r.capsule == capsule) + .count() + >= PENDING_PER_CAPSULE_CAP + { + return false; + } + while records.len() >= LEDGER_CAP { + let oldest_evictable = records + .values() + .filter(|r| r.status.is_terminal() && !r.status.is_money_bearing()) + .min_by_key(|r| r.seq) + .map(|r| r.idempotency_key.clone()); + match oldest_evictable { + Some(k) => { + records.remove(&k); + } + None => return false, + } + } + true +} + +/// A durable, bounded ledger of rail attempts. All mutations persist snapshot-atomically before +/// returning success; a persist failure rolls the mutation back and reports it (the caller decides +/// what that means — the pay path proceeds and says "unrecorded", the reconcile path REFUSES). +pub struct PaymentLedger { + records: RwLock>, + next_seq: std::sync::atomic::AtomicU64, + storage_path: Option, + /// Exclusive advisory flock on `.lock`, held for the ledger's lifetime (council S30 + /// RT-F8/G-F1): the ledger gates money on release, so it carries the METER's single-opener + /// discipline — a second live instance could last-writer-wins RESURRECT a resolved entry to + /// pending and reopen refund-exactly-once across processes. + _lock_file: Option, +} + +impl PaymentLedger { + /// In-memory ledger (tests/embedded). + pub fn new() -> Self { + Self { + records: RwLock::new(HashMap::new()), + next_seq: std::sync::atomic::AtomicU64::new(0), + storage_path: None, + _lock_file: None, + } + } + + /// Open the durable ledger. Missing file ⇒ fresh; corrupt/oversized/dup-key snapshot ⇒ REFUSE + /// (fail-closed — booting over a lost pending set would orphan reconciliation obligations). + pub fn open_durable(path: PathBuf) -> std::io::Result { + #[cfg(unix)] + let lock_file = { + use std::os::unix::io::AsRawFd as _; + let lock_path = path.with_extension("lock"); + let f = std::fs::OpenOptions::new() + .create(true) + .truncate(false) + .write(true) + .open(&lock_path)?; + let rc = unsafe { libc::flock(f.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) }; + if rc != 0 { + return Err(std::io::Error::new( + std::io::ErrorKind::WouldBlock, + "payment ledger is already open elsewhere (single-opener, fail-closed)", + )); + } + Some(f) + }; + #[cfg(not(unix))] + let lock_file = None; + let mut records = HashMap::new(); + let mut next_seq = 0u64; + match std::fs::read(&path) { + Ok(bytes) => { + if bytes.len() > 8 * 1024 * 1024 { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidData, + "payment ledger snapshot exceeds the 8 MiB bound", + )); + } + let snapshot: LedgerSnapshotV1 = serde_json::from_slice(&bytes) + .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?; + if snapshot.version != LEDGER_SNAPSHOT_VERSION { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidData, + format!("unsupported ledger snapshot version {}", snapshot.version), + )); + } + next_seq = snapshot.next_seq; + for rec in snapshot.records { + if records.insert(rec.idempotency_key.clone(), rec).is_some() { + return Err(std::io::Error::new( + std::io::ErrorKind::InvalidData, + "duplicate idempotency key in ledger snapshot", + )); + } + } + } + Err(e) if e.kind() == std::io::ErrorKind::NotFound => {} + Err(e) => return Err(e), + } + Ok(Self { + records: RwLock::new(records), + next_seq: std::sync::atomic::AtomicU64::new(next_seq), + storage_path: Some(path), + _lock_file: lock_file, + }) + } + + /// Record one rail attempt. Returns `true` iff the entry is durably recorded — `false` means + /// the caller's user-facing reason must say "unrecorded; reconcile from the error log" + /// (a full pending set or a failed persist NEVER blocks the payment's own money semantics). + /// Insert an entry at a chosen status, without the begin/finalize custody protocol. + /// + /// TEST/SEEDING ONLY: the production pay path records attempts via + /// [`begin_attempt`](Self::begin_attempt) + [`finalize`](Self::finalize) (record-before- + /// broadcast), and reconciliation resolves via [`resolve`](Self::resolve). This direct insert + /// survives as the way tests seed a ledger into a known state. A key already present is left + /// untouched (`false`): the first record wins — a replayed key cannot rewrite history. + pub fn record( + &self, + idempotency_key: &str, + capsule: &str, + payee: &str, + amount: u64, + status: PaymentStatus, + rail_note: &str, + ) -> bool { + self.record_with_token( + idempotency_key, + capsule, + payee, + amount, + status, + rail_note, + None, + ) + } + + /// Like [`record`](Self::record) — TEST/SEEDING ONLY — but binds the mandate token + /// (`standing_grant_id`) onto the entry so a later reconciliation can key the confirmed + /// settlement back onto the mandate's receipt. `record` is exactly `record_with_token(.., None)`. + #[allow(clippy::too_many_arguments)] + pub fn record_with_token( + &self, + idempotency_key: &str, + capsule: &str, + payee: &str, + amount: u64, + status: PaymentStatus, + rail_note: &str, + token_id: Option<&str>, + ) -> bool { + self.record_on_rail( + idempotency_key, + capsule, + payee, + amount, + status, + rail_note, + token_id, + PaymentRail::Unknown, + ) + } + + /// Like [`record_with_token`](Self::record_with_token) — TEST/SEEDING ONLY — but also stamps the + /// structured [`PaymentRail`] discriminator (Sprint 44), so a test can seed a positively-tagged + /// (e.g. `Http` or `Drm`) record for the reconciler's rail-aware selection. + #[allow(clippy::too_many_arguments)] + pub fn record_on_rail( + &self, + idempotency_key: &str, + capsule: &str, + payee: &str, + amount: u64, + status: PaymentStatus, + rail_note: &str, + token_id: Option<&str>, + rail: PaymentRail, + ) -> bool { + let mut records = match self.records.write() { + Ok(r) => r, + Err(_) => return false, + }; + if records.contains_key(idempotency_key) { + return false; + } + if !admit_new_key(&mut records, capsule, status == PaymentStatus::Pending) { + return false; + } + let seq = self + .next_seq + .fetch_add(1, std::sync::atomic::Ordering::SeqCst); + records.insert( + idempotency_key.to_string(), + PaymentRecord { + idempotency_key: idempotency_key.to_string(), + capsule: capsule.to_string(), + payee: payee.to_string(), + amount, + status, + rail_note: sanitize_rail_note(rail_note), + seq, + refund_applied: false, + token_id: token_id.map(str::to_string), + rail, + }, + ); + if self.persist_locked(&records).is_err() { + records.remove(idempotency_key); + return false; + } + true + } + + /// Durably custody a payment attempt as `Pending` BEFORE any money moves (council S35 red-team + /// F1). The pay path calls this AFTER reserving the cap and BEFORE broadcasting, so a + /// re-dispatch can never find "no entry" for a buy whose money moved: + /// - key absent ⇒ insert a `Pending` placeholder (subject to the per-capsule pending cap + + /// the money-bearing-aware ledger bound) ⇒ `Started`, or `CapacityRefused` if it cannot be + /// custodied; + /// - key present + money-bearing (`Pending`/`Performed`/`ResolvedCharged`) ⇒ `AlreadyActive` + /// (a concurrent dispatch beat this one; the caller must not move money again); + /// - key present + provably-nothing-moved (`NotCharged`/`ResolvedNotCharged`) ⇒ REOPEN to + /// `Pending` (a legitimate retry the guard allows) ⇒ `Started`. + /// + /// The caller then moves money and calls [`finalize`](Self::finalize) with the outcome. + /// Records the attempt on the [`Unknown`](PaymentRail::Unknown) rail; the production pay path + /// uses [`begin_attempt_on_rail`](Self::begin_attempt_on_rail) to stamp the paying rail. + pub fn begin_attempt( + &self, + idempotency_key: &str, + capsule: &str, + payee: &str, + amount: u64, + token_id: Option<&str>, + ) -> BeginAttempt { + self.begin_attempt_on_rail( + idempotency_key, + capsule, + payee, + amount, + token_id, + PaymentRail::Unknown, + ) + } + + /// [`begin_attempt`](Self::begin_attempt) that also stamps the structured [`PaymentRail`] + /// (Sprint 44), so the DRM reconciler identifies its pendings by tag, not by the rail-controlled + /// `rail_note`. A REOPEN adopts the new attempt's rail (the same key retried on a different rail + /// takes the new rail — the money that actually moves is this attempt's). + #[allow(clippy::too_many_arguments)] + pub fn begin_attempt_on_rail( + &self, + idempotency_key: &str, + capsule: &str, + payee: &str, + amount: u64, + token_id: Option<&str>, + rail: PaymentRail, + ) -> BeginAttempt { + let mut records = match self.records.write() { + Ok(r) => r, + Err(_) => return BeginAttempt::CapacityRefused, + }; + if let Some(existing) = records.get(idempotency_key) { + if existing.status.is_money_bearing() { + return BeginAttempt::AlreadyActive(existing.status); + } + // A provably-nothing-moved terminal ⇒ reopen to Pending for the retry. Snapshot the + // WHOLE prior record so a failed persist restores exact memory⇄disk agreement — + // including `rail_note`, `rail`, and the `refund_applied` forensics bit, not just the + // status. + let prev = existing.clone(); + if let Some(r) = records.get_mut(idempotency_key) { + r.status = PaymentStatus::Pending; + r.rail_note = sanitize_rail_note("reserving"); + r.refund_applied = false; + r.rail = rail; + } + if self.persist_locked(&records).is_err() { + records.insert(idempotency_key.to_string(), prev); // roll back the reopen + return BeginAttempt::CapacityRefused; + } + return BeginAttempt::Started; + } + // New key: the same per-capsule pending cap + money-bearing-aware eviction as `record`. + if !admit_new_key(&mut records, capsule, true) { + return BeginAttempt::CapacityRefused; + } + let seq = self + .next_seq + .fetch_add(1, std::sync::atomic::Ordering::SeqCst); + records.insert( + idempotency_key.to_string(), + PaymentRecord { + idempotency_key: idempotency_key.to_string(), + capsule: capsule.to_string(), + payee: payee.to_string(), + amount, + status: PaymentStatus::Pending, + rail_note: sanitize_rail_note("reserving"), + seq, + refund_applied: false, + token_id: token_id.map(str::to_string), + rail, + }, + ); + if self.persist_locked(&records).is_err() { + records.remove(idempotency_key); + return BeginAttempt::CapacityRefused; + } + BeginAttempt::Started + } + + /// Record the OUTCOME of a `begin_attempt` custody, transitioning the `Pending` placeholder to + /// its final status + rail note (council S35 red-team F1). Only a `Pending` entry is updated + /// (never clobbers a resolved one); a `Pending` target status keeps it Pending with the tx in + /// the note (the DRM broadcast-accepted case). Best-effort persist — the in-memory state is + /// authoritative for the guard; a persist failure is logged by the caller. + pub fn finalize(&self, idempotency_key: &str, status: PaymentStatus, rail_note: &str) -> bool { + let mut records = match self.records.write() { + Ok(r) => r, + Err(_) => return false, + }; + match records.get_mut(idempotency_key) { + Some(r) if r.status == PaymentStatus::Pending => { + r.status = status; + r.rail_note = sanitize_rail_note(rail_note); + } + _ => return false, + } + let _ = self.persist_locked(&records); + true + } + + /// Resolve a PENDING entry exactly once. Durable-before-visible with rollback: on success the + /// entry is terminally `ResolvedCharged`/`ResolvedNotCharged` and can never resolve again + /// (the double-refund guard the reconcile handler builds on). Errors are honest strings. + pub fn resolve( + &self, + idempotency_key: &str, + charged: bool, + ) -> Result { + let mut records = self.records.write().map_err(|_| ResolveError::Lock)?; + let rec = records + .get_mut(idempotency_key) + .ok_or(ResolveError::NotFound)?; + if rec.status != PaymentStatus::Pending { + return Err(ResolveError::NotPending(rec.status)); + } + rec.status = if charged { + PaymentStatus::ResolvedCharged + } else { + PaymentStatus::ResolvedNotCharged + }; + let resolved = rec.clone(); + if self.persist_locked(&records).is_err() { + if let Some(r) = records.get_mut(idempotency_key) { + r.status = PaymentStatus::Pending; + } + return Err(ResolveError::Persist); + } + Ok(resolved) + } + + /// Mark a `ResolvedNotCharged` entry's refund as durably applied (called by the reconcile + /// handler AFTER `try_refund` returns Ok). Best-effort durable: a persist failure keeps the + /// in-memory mark (the refund DID apply; disk catches up at the next mutation) — the forensic + /// meaning of `refund_applied=false` on disk is "refund may be lost, check the chain event". + pub fn mark_refund_applied(&self, idempotency_key: &str) -> bool { + let mut records = match self.records.write() { + Ok(r) => r, + Err(_) => return false, + }; + match records.get_mut(idempotency_key) { + Some(r) if r.status == PaymentStatus::ResolvedNotCharged => { + r.refund_applied = true; + } + _ => return false, + } + let _ = self.persist_locked(&records); + true + } + + /// All PENDING entries (the reconciliation work list), oldest first. + pub fn pending(&self) -> Vec { + let records = match self.records.read() { + Ok(r) => r, + Err(_) => return Vec::new(), + }; + let mut out: Vec = records + .values() + .filter(|r| r.status == PaymentStatus::Pending) + .cloned() + .collect(); + out.sort_by_key(|r| r.seq); + out + } + + /// Sum + count of one capsule's PENDING (indeterminate) units — the "held, unconfirmed" figure + /// the budget surface shows next to confirmed spend (council S29 RT-F4). + pub fn pending_for(&self, capsule: &str) -> (u64, usize) { + let records = match self.records.read() { + Ok(r) => r, + Err(_) => return (0, 0), + }; + records + .values() + .filter(|r| r.status == PaymentStatus::Pending && r.capsule == capsule) + .fold((0u64, 0usize), |(units, n), r| { + (units.saturating_add(r.amount), n + 1) + }) + } + + /// One entry by key (read-only projection). + pub fn get(&self, idempotency_key: &str) -> Option { + self.records.read().ok()?.get(idempotency_key).cloned() + } + + /// How many entries the ledger holds (read-only projection; 0 on a poisoned lock, matching + /// `pending()`'s convention). + pub fn len(&self) -> usize { + self.records.read().map(|r| r.len()).unwrap_or(0) + } + + /// True when the ledger holds no entries. + pub fn is_empty(&self) -> bool { + self.len() == 0 + } + + /// The most recent `limit` entries across ALL statuses, newest first (read-only projection — + /// the Marketplace panel's buys table, which pairs it with `pending()` so a live obligation + /// is never truncated away). Bounded by the caller; the ledger itself is bounded by + /// `LEDGER_CAP`. + pub fn recent(&self, limit: usize) -> Vec { + let records = match self.records.read() { + Ok(r) => r, + Err(_) => return Vec::new(), + }; + let mut out: Vec = records.values().cloned().collect(); + out.sort_by_key(|r| std::cmp::Reverse(r.seq)); + out.truncate(limit); + out + } + + /// Snapshot write, mirroring the spend meter's discipline (temp + fsync + rename + parent-dir + /// fsync). Memory-only ⇒ no-op. The ledger does not poison: it is operational custody, and its + /// callers already treat a failed write as "unrecorded, say so" / "refuse the resolution". + fn persist_locked(&self, records: &HashMap) -> std::io::Result<()> { + let Some(path) = &self.storage_path else { + return Ok(()); + }; + let mut list: Vec = records.values().cloned().collect(); + list.sort_by_key(|r| r.seq); + let content = serde_json::to_vec(&LedgerSnapshotV1 { + version: LEDGER_SNAPSHOT_VERSION, + next_seq: self.next_seq.load(std::sync::atomic::Ordering::SeqCst), + records: list, + }) + .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?; + let tmp_path = path.with_extension("tmp"); + { + use std::io::Write as _; + let mut tmp = std::fs::File::create(&tmp_path)?; + tmp.write_all(&content)?; + tmp.sync_all()?; + } + std::fs::rename(&tmp_path, path)?; + #[cfg(unix)] + if let Some(parent) = path.parent() { + std::fs::File::open(parent)?.sync_all()?; + } + Ok(()) + } +} + +impl Default for PaymentLedger { + fn default() -> Self { + Self::new() + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn pending_entries_survive_restart_and_resolve_exactly_once() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("payments.json"); + { + let ledger = PaymentLedger::open_durable(path.clone()).unwrap(); + assert!(ledger.record("flint-k1", "vm-ap", "acme", 200, PaymentStatus::Pending, "")); + assert!(ledger.record( + "flint-k2", + "vm-ap", + "acme", + 50, + PaymentStatus::Performed, + "rail-ref-9" + )); + assert_eq!(ledger.pending_for("vm-ap"), (200, 1)); + } // restart + let ledger = PaymentLedger::open_durable(path.clone()).unwrap(); + assert_eq!( + ledger.pending_for("vm-ap"), + (200, 1), + "the reconciliation obligation survives restart" + ); + assert_eq!( + ledger.get("flint-k2").unwrap().rail_note, + "rail-ref-9", + "the rail reference is durably custodied" + ); + let resolved = ledger.resolve("flint-k1", false).unwrap(); + assert_eq!(resolved.status, PaymentStatus::ResolvedNotCharged); + assert!( + ledger.resolve("flint-k1", false).is_err(), + "a payment resolves EXACTLY once — no double-refund handle" + ); + assert_eq!(ledger.pending_for("vm-ap"), (0, 0)); + // The resolution also survives restart. + drop(ledger); + let reopened = PaymentLedger::open_durable(path).unwrap(); + assert!(reopened.resolve("flint-k1", true).is_err()); + } + + #[test] + fn record_is_first_write_wins_and_notes_are_sanitized() { + let ledger = PaymentLedger::new(); + assert!(ledger.record( + "k", + "vm-ap", + "acme", + 10, + PaymentStatus::Pending, + "ok\x1b[31m