chio_kernel_core/
lib.rs

1//! Portable Chio kernel core.
2//!
3//! This crate contains the pure-compute subset of Chio evaluation as a
4//! `no_std + alloc` library so the same verdict-producing code can run
5//! inside a browser (wasm32-unknown-unknown), a Cloudflare Worker
6//! (wasm32-wasip1), a mobile app (UniFFI static lib), or the desktop
7//! sidecar (`chio-kernel`). The contract is described in
8//! `docs/protocols/PORTABLE-KERNEL-ARCHITECTURE.md`.
9//!
10//! # What lives here
11//!
12//! - [`Verdict`] -- the three-valued outcome of an evaluation.
13//! - [`Guard`] -- the sync guard trait (identical signature to
14//!   `chio_kernel::Guard`, modulo `Error` surface mapped onto [`KernelCoreError`]).
15//! - [`GuardContext`] -- the inputs a guard sees.
16//! - [`evaluate`] -- pure compute that walks a capability + request through
17//!   the sync checks (signature, time, subject binding, scope, guard pipeline)
18//!   and returns `Ok(Verdict::Allow)` or `Ok(Verdict::Deny { reason })`. No
19//!   I/O, no budget mutation, no revocation lookup.
20//! - [`verify_capability`] -- offline capability verification used by tools
21//!   that only need to inspect a token (no scope, no revocation).
22//! - [`sign_receipt`] -- WYSIWYS signing: recompute `content_hash` over the
23//!   supplied canonical content inside the trust boundary and refuse on
24//!   mismatch (fail-closed). The production signing primitive.
25//! - [`sign_receipt_with_handle`] -- WYSIWYS signing bound to a one-time,
26//!   move-only signing handle (the strongest API; cannot be replayed).
27//! - [`sign_receipt_relaying_trusted_body`] -- body-only relay that trusts the
28//!   caller `content_hash`; for transport adapters that cannot hold the content
29//!   preimage (mobile/browser/cpp-ffi). Explicit, auditable trust seam.
30//! - [`Clock`] / [`Rng`] -- abstract trait boundaries for time/entropy so
31//!   adapters on wasm/mobile can inject platform clocks and CSPRNGs.
32//!
33//! # What stays in `chio-kernel`
34//!
35//! The full `chio-kernel` crate keeps every piece that actually touches I/O
36//! or async: `tokio` tasks, `rusqlite` receipt/revocation/budget stores,
37//! `ureq` price-oracle client, `lru` DPoP nonce cache, async session ops,
38//! HTTP/stdio transport, nested-flow bridges, tool-server dispatch. Those
39//! modules depend on `chio-kernel-core` for the pure-compute kernels but
40//! add the IO glue around them.
41//!
42//! # `no_std` status
43//!
44//! The crate is `#![no_std]` with `extern crate alloc;`. At the source level
45//! we never name `std::*`, and the portable proof is scripted in
46//! `scripts/check-portable-kernel.sh`.
47//!
48//! That proof runs both:
49//! - `cargo build -p chio-kernel-core --no-default-features`
50//! - `cargo build -p chio-kernel-core --target wasm32-unknown-unknown --no-default-features`
51//!
52//! The browser and mobile adapter crates perform their own platform-specific
53//! qualification on top of this core.
54
55#![no_std]
56#![cfg_attr(test, allow(clippy::expect_used, clippy::unwrap_used))]
57#![deny(unsafe_code)]
58
59extern crate alloc;
60
61pub mod budget_split;
62pub mod capability_verify;
63pub mod clock;
64pub mod evaluate;
65pub(crate) mod formal_aeneas;
66pub(crate) mod formal_core;
67#[cfg(feature = "fuzz")]
68pub mod fuzz;
69pub mod guard;
70pub mod normalized;
71pub mod passport_verify;
72pub mod receipts;
73#[cfg(feature = "revocation-view")]
74pub mod revocation_view;
75pub mod rng;
76pub mod scope;
77
78pub use budget_split::{
79    BudgetRegistry, BudgetSplit, BudgetSplitError, InMemoryBudgetRegistry, NoopBudgetRegistry,
80    MAX_BUDGET_SHARE_BPS,
81};
82pub use capability_verify::{
83    verify_capability, verify_capability_full, verify_capability_full_with_root,
84    verify_capability_with_floor, verify_capability_with_floor_and_resolver,
85    verify_capability_with_floor_and_trust_root, verify_capability_with_negotiated_floor,
86    CapabilityError, CapabilityFeatureContext, TrustRootResolver, VerifiedCapability,
87};
88pub use clock::{Clock, FixedClock};
89pub use evaluate::{
90    evaluate, evaluate_with_crypto_floor, evaluate_with_crypto_floor_and_budgets,
91    evaluate_with_full_floor, evaluate_with_full_floor_and_root, EvaluateInput, EvaluationVerdict,
92    KernelCoreError,
93};
94pub use guard::{Guard, GuardContext, PortableToolCallRequest};
95pub use normalized::{
96    NormalizationError, NormalizedCapability, NormalizedConstraint, NormalizedEvaluationVerdict,
97    NormalizedMonetaryAmount, NormalizedOperation, NormalizedPromptGrant, NormalizedRequest,
98    NormalizedResourceGrant, NormalizedRuntimeAssuranceTier, NormalizedScope, NormalizedToolGrant,
99    NormalizedVerdict, NormalizedVerifiedCapability,
100};
101pub use passport_verify::{
102    verify_parsed_passport, verify_passport, PortablePassportBody, PortablePassportEnvelope,
103    VerifiedPassport, VerifyError, PORTABLE_PASSPORT_SCHEMA,
104};
105pub use receipts::{
106    sign_receipt, sign_receipt_relaying_trusted_body, sign_receipt_with_handle, ReceiptSigningError,
107};
108#[cfg(feature = "revocation-view")]
109pub use revocation_view::{
110    RevocationSnapshot, RevocationView, RevocationViewError, RevocationViewSubject,
111};
112pub use rng::{NullRng, Rng};
113pub use scope::{MatchedGrant, ScopeMatchError};
114
115#[cfg(kani)]
116mod kani_harnesses;
117
118#[cfg(kani)]
119mod kani_public_harnesses;
120
121/// Three-valued outcome of a kernel evaluation step.
122///
123/// This mirrors `chio_kernel::runtime::Verdict` exactly. The
124/// kernel core never emits `PendingApproval` itself; the full `chio-kernel`
125/// orchestration shell wraps the core verdict with the human-in-the-loop
126/// approval path where needed.
127#[derive(Debug, Clone, Copy, PartialEq, Eq)]
128pub enum Verdict {
129    /// The action is allowed.
130    Allow,
131    /// The action is denied.
132    Deny,
133    /// The action is suspended pending a human decision. Only produced by
134    /// the full `chio-kernel` shell, never by `chio-kernel-core` directly.
135    PendingApproval,
136}
chio_kernel_core/lib.rs

chio_kernel_core/
lib.rs
