Skip to main content

Crate octosense_app_contract

Crate octosense_app_contract 

Source
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.

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 runs cargo semver-checks against the latest published 1.x on every change.

  • Every public struct and enum is #[non_exhaustive] (the one exception is the unit marker RefuseAllSignatures), so adding a field or a variant is a minor change. Build what you need with HostLimits::default / HostLimits::system and the with_* methods, Signature::new, parse for manifests and policy::resolve for policies; match enums with a _ arm.

  • Unknown manifest fields are classified, not ignored. Every field added in 1.x is 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 in requires. Parsing (parse) applies, in this order:

    1. schema must be SCHEMA (1 for the whole 1.x line).
    2. Every requires entry must be in KNOWN_FEATURES, at every schema_minor; otherwise the app is refused with app <id> needs a newer host: <feature>. 1.0.0 knows none.
    3. A manifest whose schema_minor (default 0) is at most SCHEMA_MINOR (0 in 1.0.0) is read strictly: an unknown field at any level refuses it, exactly as before requires existed.
    4. A manifest whose schema_minor is above SCHEMA_MINOR was written for a newer 1.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 by AppManifest::ignored_fields for the host to log. Fields this build knows are still checked as always, and a research object 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.x must therefore be skipped when serialising its default and must serialise exactly as it is written.

  • Both new fields are invisible to older manifests. requires and schema_minor are 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 resolved AppPolicy; every 1.x release must reproduce all of them, and the corpus is append-only within 1.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 research and crawl capabilities.
verify
Admitting a bundle: the hash always, the signature when the host asks.