Expand description
The OctoSense app contract: what an app or a host needs to read, check and run an app package, and nothing else (OctoSense ADR 0005).
App Hub, the OctoSense shell and every app that runs other apps (Rinx’s
mini apps) depend on this crate by version, octosense-app-contract = "1", so Cargo links one 1.x for the whole build and App Hub can change
its store, catalog and runner without forcing an app release.
- Manifest:
AppManifestand its parts,SCHEMA,MANIFEST_FILE,parse. - Policy:
policy::resolve,HostLimits,AppPolicy: the capabilities, network hosts, storage and budgets an app gets. - Integrity:
digest_dir,bundle_digest,admit,admit_digest,SignatureVerifier,RefuseAllSignatures. - Running a package:
SCRIPT_ENTRY,script_source,ASSETS_PLACEHOLDER,AssetServer,StaticAssets,rewrite_assets.
What an app may do is in the contract; how a host sandboxes it is not.
Each host turns an AppPolicy into its own sandbox settings under one
rule: a host may restrict more than the policy says, never less.
The order is always: parse → admit (or admit_digest) →
policy::resolve. Skipping a step is the bug this crate exists to make
hard.
use octosense_app_contract::{admit, bundle_digest, parse, policy, HostLimits, RefuseAllSignatures};
let bundle = b"the card bundle bytes";
let manifest = format!(
r#"{{"schema":1,"id":"forecast","version":"1.0.0","name":"Forecast",
"integrity":{{"bundle_blake3":"{}"}},
"capabilities":["storage","net"],
"network":{{"hosts":["api.weather.example"]}}}}"#,
bundle_digest(bundle)
);
let manifest = parse(&manifest).unwrap();
admit(&manifest, bundle, &RefuseAllSignatures).unwrap();
let limits = HostLimits::default().with_require_signature(false);
let policy = policy::resolve(&manifest, &limits).unwrap();
assert!(policy.allows_host("api.weather.example"));
assert!(!policy.allows_host("example.com"));§Stability
Within 1.x the contract only grows (ADR 0005 §2):
-
Additive only. New types, functions, optional manifest fields and enum variants; nothing is removed or renamed, and no existing field, default or rule changes meaning. Anything else is
2.0, decided in an ADR. CI runscargo semver-checksagainst the latest published1.xon every change. -
Every public struct and enum is
#[non_exhaustive](the one exception is the unit markerRefuseAllSignatures), so adding a field or a variant is a minor change. Build what you need withHostLimits::default/HostLimits::systemand thewith_*methods,Signature::new,parsefor manifests andpolicy::resolvefor policies; match enums with a_arm. -
Unknown manifest fields are classified, not ignored. Every field added in
1.xis either optional (a host that does not know it may run the app without it: it only adds information or asks for less) or required (it restricts or changes what the app gets). A manifest that uses a required field names its feature inrequires. Parsing (parse) applies, in this order:schemamust beSCHEMA(1for the whole1.xline).- Every
requiresentry must be inKNOWN_FEATURES, at everyschema_minor; otherwise the app is refused withapp <id> needs a newer host: <feature>.1.0.0knows none. - A manifest whose
schema_minor(default 0) is at mostSCHEMA_MINOR(0in1.0.0) is read strictly: an unknown field at any level refuses it, exactly as beforerequiresexisted. - A manifest whose
schema_minoris aboveSCHEMA_MINORwas written for a newer1.x. Its unknown fields, at any level (top level,network,storage,agent,agent.model, …), are optional by rule 2, so they are ignored and reported byAppManifest::ignored_fieldsfor the host to log. Fields this build knows are still checked as always, and aresearchobject in the old toolbox shape is still refused.
So an older host never runs an app under weaker rules than its author wrote, and a newer optional field never breaks an older host. The ignored fields stay part of the manifest’s signing bytes, so a newer manifest’s signature still verifies; a field added in
1.xmust therefore be skipped when serialising its default and must serialise exactly as it is written. -
Both new fields are invisible to older manifests.
requiresandschema_minorare left out of the canonical signing bytes when empty, so every manifest signed before them signs exactly as it did. -
Behaviour is pinned by fixtures.
tests/fixtures/holds real manifests and packages with their digest, signing bytes, ignored fields and resolvedAppPolicy; every1.xrelease must reproduce all of them, and the corpus is append-only within1.x.
Re-exports§
pub use assets::rewrite_assets;pub use assets::AssetServer;pub use assets::StaticAssets;pub use bundle::digest_dir;pub use bundle::portable_path;pub use bundle::MANIFEST_FILE;pub use entry::script_source;pub use entry::ASSETS_PLACEHOLDER;pub use entry::SCRIPT_ENTRY;pub use manifest::check_component_id;pub use manifest::check_reserved_id;pub use manifest::is_exact_version;pub use manifest::parse;pub use manifest::short_id;pub use manifest::AgentSpec;pub use manifest::AgentWorkspace;pub use manifest::AppManifest;pub use manifest::ComponentDependency;pub use manifest::Compute;pub use manifest::GithubPublisher;pub use manifest::Integrity;pub use manifest::ModelNeed;pub use manifest::ModelSpec;pub use manifest::ModelTier;pub use manifest::Network;pub use manifest::ProfileMode;pub use manifest::Signature;pub use manifest::Storage;pub use manifest::TaskModel;pub use manifest::Triggers;pub use manifest::KNOWN_CAPABILITIES;pub use manifest::KNOWN_FEATURES;pub use manifest::KNOWN_MODEL_NEEDS;pub use manifest::MAX_COMPONENTS;pub use manifest::RESERVED_HOST_FILE_IDS;pub use manifest::RESERVED_NAMES;pub use manifest::SCHEMA;pub use manifest::SCHEMA_MINOR;pub use policy::resolve;pub use policy::AppPolicy;pub use policy::HostLimits;pub use policy::StorageGrant;pub use research::ResearchScope;pub use verify::admit;pub use verify::admit_digest;pub use verify::bundle_digest;pub use verify::verify_manifest;pub use verify::RefuseAllSignatures;pub use verify::SignatureVerifier;
Modules§
- assets
- Serving an installed app its own artwork, and nothing else.
- backend
- Public backend registrations are signed app metadata; credentials are not.
- bundle
- What exactly gets hashed.
- entry
- What a bundle runs: an L0 card, or a script app.
- host_
api - Versioned host API descriptions and bundle compatibility requirements.
- manifest
- What an installed app declares about itself.
- palpo
- Exact Palpo service grants and their consent language. Passwordless Palpo operations. Credentials belong to the host. Granting an operation never changes Matrix admin/owner/membership authority.
- policy
- Resolving a manifest into what the app actually gets.
- research
- The scope of the
researchandcrawlcapabilities. - verify
- Admitting a bundle: the hash always, the signature when the host asks.