Skip to main content

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;