octosense_app_contract/lib.rs
1//! The OctoSense app contract: what an app or a host needs to read, check
2//! and run an app package, and nothing else (OctoSense ADR 0005).
3//!
4//! App Hub, the OctoSense shell and every app that runs other apps (Rinx's
5//! mini apps) depend on this crate by version, `octosense-app-contract =
6//! "1"`, so Cargo links one `1.x` for the whole build and App Hub can change
7//! its store, catalog and runner without forcing an app release.
8//!
9//! - **Manifest:** [`AppManifest`] and its parts, [`SCHEMA`],
10//! [`MANIFEST_FILE`], [`parse`].
11//! - **Policy:** [`policy::resolve`], [`HostLimits`], [`AppPolicy`]: the
12//! capabilities, network hosts, storage and budgets an app gets.
13//! - **Integrity:** [`digest_dir`], [`bundle_digest`], [`admit`],
14//! [`admit_digest`], [`SignatureVerifier`], [`RefuseAllSignatures`].
15//! - **Running a package:** [`SCRIPT_ENTRY`], [`script_source`],
16//! [`ASSETS_PLACEHOLDER`], [`AssetServer`], [`StaticAssets`],
17//! [`rewrite_assets`].
18//!
19//! What an app may do is in the contract; how a host sandboxes it is not.
20//! Each host turns an [`AppPolicy`] into its own sandbox settings under one
21//! rule: **a host may restrict more than the policy says, never less.**
22//!
23//! The order is always: [`parse`] → [`admit`] (or [`admit_digest`]) →
24//! [`policy::resolve`]. Skipping a step is the bug this crate exists to make
25//! hard.
26//!
27//! ```
28//! use octosense_app_contract::{admit, bundle_digest, parse, policy, HostLimits, RefuseAllSignatures};
29//! let bundle = b"the card bundle bytes";
30//! let manifest = format!(
31//! r#"{{"schema":1,"id":"forecast","version":"1.0.0","name":"Forecast",
32//! "integrity":{{"bundle_blake3":"{}"}},
33//! "capabilities":["storage","net"],
34//! "network":{{"hosts":["api.weather.example"]}}}}"#,
35//! bundle_digest(bundle)
36//! );
37//! let manifest = parse(&manifest).unwrap();
38//! admit(&manifest, bundle, &RefuseAllSignatures).unwrap();
39//! let limits = HostLimits::default().with_require_signature(false);
40//! let policy = policy::resolve(&manifest, &limits).unwrap();
41//! assert!(policy.allows_host("api.weather.example"));
42//! assert!(!policy.allows_host("example.com"));
43//! ```
44//!
45//! # Stability
46//!
47//! Within `1.x` the contract only grows (ADR 0005 §2):
48//!
49//! - **Additive only.** New types, functions, optional manifest fields and
50//! enum variants; nothing is removed or renamed, and no existing field,
51//! default or rule changes meaning. Anything else is `2.0`, decided in an
52//! ADR. CI runs `cargo semver-checks` against the latest published `1.x`
53//! on every change.
54//! - **Every public struct and enum is `#[non_exhaustive]`** (the one
55//! exception is the unit marker [`RefuseAllSignatures`]), so adding a
56//! field or a variant is a minor change. Build what you need with
57//! [`HostLimits::default`] / [`HostLimits::system`] and the `with_*`
58//! methods, [`Signature::new`], [`parse`] for manifests and
59//! [`policy::resolve`] for policies; match enums with a `_` arm.
60//! - **Unknown manifest fields are classified, not ignored.** Every field
61//! added in `1.x` is either *optional* (a host that does not know it may
62//! run the app without it: it only adds information or asks for less) or
63//! *required* (it restricts or changes what the app gets). A manifest
64//! that uses a required field names its feature in `requires`. Parsing
65//! ([`parse`]) applies, in this order:
66//! 1. `schema` must be [`SCHEMA`] (`1` for the whole `1.x` line).
67//! 2. Every `requires` entry must be in [`KNOWN_FEATURES`], at every
68//! `schema_minor`; otherwise the app is refused with
69//! `app <id> needs a newer host: <feature>`. `1.0.0` knows none.
70//! 3. A manifest whose `schema_minor` (default 0) is at most
71//! [`SCHEMA_MINOR`] (`0` in `1.0.0`) is read strictly: an unknown
72//! field at any level refuses it, exactly as before `requires`
73//! existed.
74//! 4. A manifest whose `schema_minor` is above [`SCHEMA_MINOR`] was
75//! written for a newer `1.x`. Its unknown fields, at any level
76//! (top level, `network`, `storage`, `agent`, `agent.model`, …), are
77//! optional by rule 2, so they are ignored and reported by
78//! [`AppManifest::ignored_fields`] for the host to log. Fields this
79//! build knows are still checked as always, and a `research` object in
80//! the old toolbox shape is still refused.
81//!
82//! So an older host never runs an app under weaker rules than its author
83//! wrote, and a newer optional field never breaks an older host. The
84//! ignored fields stay part of the manifest's signing bytes, so a newer
85//! manifest's signature still verifies; a field added in `1.x` must
86//! therefore be skipped when serialising its default and must serialise
87//! exactly as it is written.
88//! - **Both new fields are invisible to older manifests.** `requires` and
89//! `schema_minor` are left out of the canonical signing bytes when empty,
90//! so every manifest signed before them signs exactly as it did.
91//! - **Behaviour is pinned by fixtures.** `tests/fixtures/` holds real
92//! manifests and packages with their digest, signing bytes, ignored
93//! fields and resolved [`AppPolicy`]; every `1.x` release must reproduce
94//! all of them, and the corpus is append-only within `1.x`.
95pub mod assets;
96pub mod backend;
97pub mod host_api;
98pub mod bundle;
99pub mod entry;
100mod lenient;
101pub mod manifest;
102pub mod policy;
103pub mod research;
104pub mod verify;
105
106pub use assets::{rewrite_assets, AssetServer, StaticAssets};
107pub use bundle::{digest_dir, portable_path, MANIFEST_FILE};
108pub use entry::{script_source, ASSETS_PLACEHOLDER, SCRIPT_ENTRY};
109pub use manifest::{
110 check_component_id, check_reserved_id, is_exact_version, parse, short_id, AgentSpec, AgentWorkspace, AppManifest, ComponentDependency,
111 Compute, GithubPublisher, Integrity, ModelNeed, ModelSpec, ModelTier, Network, ProfileMode, Signature, Storage, TaskModel, Triggers,
112 KNOWN_CAPABILITIES, KNOWN_FEATURES, KNOWN_MODEL_NEEDS, MAX_COMPONENTS, RESERVED_HOST_FILE_IDS, RESERVED_NAMES, SCHEMA, SCHEMA_MINOR,
113};
114pub use policy::{resolve, AppPolicy, HostLimits, StorageGrant};
115pub use research::ResearchScope;
116pub use verify::{admit, admit_digest, bundle_digest, verify_manifest, RefuseAllSignatures, SignatureVerifier};
117
118/// Exact Palpo service grants and their consent language.
119pub mod palpo;