Apps

[Hadamcik]

Reviewer map

sage-apps crate

Sage Apps is built around one core rule: backend owns state and authority. The frontend is only a presentation layer and is not trusted to decide permissions, app identity, runtime state, wallet scope, approval results, install/update validity, or storage/origin ownership.

Most sensitive behavior is intentionally funneled through a small exported surface from crates/sage-apps/src/lib.rs, so lib.rs is the best first review file.

crates/sage-apps/src/lib.rs

The crate exports the following authority entry points:

// State
pub use db::AppsDb;
pub use host::AppsHostState;

// Commands
pub use bridge::commands::{apps_invoke_bridge, apps_invoke_system_bridge};
pub use environment::commands::apps_set_environment_theme;
pub use lifecycle::{
    apps_clear_runtime_browsing_data,
    install::commands::apps_list_installed_apps,
    uninstall::apps_uninstall_app,
    update::commands::{apps_apply_app_update, apps_check_app_update},
};
pub use runtime::commands::{
    apps_clear_active_taskbar_runtime, apps_dev_reload_runtime, apps_enter_workspace,
    apps_focus_taskbar_runtime, apps_kill_taskbar_runtime, apps_leave_workspace,
    apps_list_runtimes, apps_start_system_app, apps_start_user_app,
};
pub use sandbox::commands::{
    apps_get_app_launch_gate, apps_get_sandbox_state, apps_rerun_sandbox_tests,
};
pub use settings::{apps_get_auto_update_enabled, apps_set_auto_update_enabled};

// Bridge protocol
pub use security::{handle_system_app_protocol_request, handle_user_app_protocol_request};

// SDK types
pub use bridge::ts_exports::{export_system_bridge_typescript, export_user_bridge_typescript};

// Operations
pub use lifecycle::{process_pending_storage_cleanup, start_background_app_update_checker};
pub use runtime::process_sage_network_change;
pub use sandbox::runner::ensure_initial_sandbox_run;

// Docs
pub use build::docs::generate_docs;

Where to go from lib.rs

lib.rs is the map of the crate boundary. From each export group, follow these review paths.

1. Bridge protocol: how apps interact with Sage

From:

pub use bridge::commands::{apps_invoke_bridge, apps_invoke_system_bridge};
pub use security::{handle_system_app_protocol_request, handle_user_app_protocol_request};

Review:

• crates/sage-apps/src/bridge/commands.rs
• crates/sage-apps/src/bridge/registry.rs
• crates/sage-apps/src/bridge/methods/shared.rs
• crates/sage-apps/src/bridge/methods/user/**
• crates/sage-apps/src/bridge/methods/system/**
• crates/sage-apps/src/security/**

Important things to verify:

• all app calls funnel through a small number of backend entry points
• user bridge and system bridge are isolated
• bridge methods explicitly declare required capabilities
• backend re-checks authority at execution time
• approval UI is not treated as authority
• runtime capability requests only allow requestable_by_app
• wallet methods enforce wallet scope

2. App isolation model: what apps are allowed to be

Review:

• crates/sage-apps/src/types/app/common.rs
• crates/sage-apps/src/types/app/wallet_scope.rs
• crates/sage-apps/src/types/invariants/permission.rs
• crates/sage-apps/src/types/permissions/**
• crates/sage-apps/src/capabilities/definitions.rs
• crates/sage-apps/src/capabilities/types.rs
• crates/sage-apps/src/db/**

Important things to verify:

• permissions are normalized in backend types
• secret access cannot coexist with external/network access
• secret access cannot coexist with tainted persistent webview storage
• wallet scope is backend-owned durable state
• capability flags are enforced consistently:
  • user_grantable
  • requestable_by_app
  • shared_with_app

3. Install/update/permission mutation: what changes app authority

Review:

• crates/sage-apps/src/lifecycle/package.rs
• crates/sage-apps/src/lifecycle/install/**
• crates/sage-apps/src/lifecycle/update/**
• crates/sage-apps/src/lifecycle/mutation/**
• crates/sage-apps/src/bridge/methods/system/app_install/**
• crates/sage-apps/src/bridge/methods/system/app_update/**
• crates/sage-apps/src/bridge/methods/system/app_permissions/**

Important things to verify:

• manifest permissions are normalized before persistence
• install/update review is backend-owned
• permission changes are diffed correctly
• wallet scope changes are backend-owned
• permission/scope changes trigger required runtime reload/reopen behavior
• ZIP extraction is bounded and cannot escape extraction root

4. Runtime lifecycle: how durable app state becomes webviews

From:

pub use runtime::commands::{
    apps_clear_active_taskbar_runtime, apps_dev_reload_runtime, apps_enter_workspace,
    apps_focus_taskbar_runtime, apps_kill_taskbar_runtime, apps_leave_workspace,
    apps_list_runtimes, apps_start_system_app, apps_start_user_app,
};
pub use runtime::process_sage_network_change;

Review:

• crates/sage-apps/src/runtime/state/**
• crates/sage-apps/src/runtime/start.rs
• crates/sage-apps/src/runtime/stop.rs
• crates/sage-apps/src/runtime/resolve.rs
• crates/sage-apps/src/runtime/webview.rs
• crates/sage-apps/src/runtime/commands.rs

Important things to verify:

• backend runtime state is authority
• user apps cannot escalate into system presentations
• runtime reload/reopen paths are centralized
• stale runtime state cannot silently survive permission/storage changes
• runtime visibility/focus is backend-controlled

5. Storage/origin rotation and cleanup

From:

pub use lifecycle::{
    apps_clear_runtime_browsing_data,
};
pub use lifecycle::{process_pending_storage_cleanup, start_background_app_update_checker};

Review:

• crates/sage-apps/src/types/storage/**
• crates/sage-apps/src/db/storage.rs
• crates/sage-apps/src/lifecycle/clear_data/**
• crates/sage-apps/src/lifecycle/storage_cleanup/**
• crates/sage-apps/src/lifecycle/update/permissions.rs

Important things to verify:

• storage and origin are explicit durable state
• clearing/rotating storage invalidates affected runtimes
• runtimes cannot continue using invalidated storage/origins
• origin taint persists correctly
• abandoned cleanup is secondary to runtime invalidation

6. Sandbox validation

From:

pub use sandbox::commands::{
    apps_get_app_launch_gate, apps_get_sandbox_state, apps_rerun_sandbox_tests,
};
pub use sandbox::runner::ensure_initial_sandbox_run;

Review:

• crates/sage-apps/src/sandbox/**
• builtin-apps/src/sandbox-test/**

Important things to verify:

• sandbox tests validate expected isolation behavior
• tests cover storage isolation
• tests cover network restrictions
• tests cover bridge restrictions
• launch gating behaves correctly

7. Secondary/supporting exports

From:

pub use settings::{apps_get_auto_update_enabled, apps_set_auto_update_enabled};
pub use bridge::ts_exports::{export_system_bridge_typescript, export_user_bridge_typescript};
pub use build::docs::generate_docs;

Review later:

• crates/sage-apps/src/settings.rs
• crates/sage-apps/src/bridge/ts_exports.rs
• crates/sage-apps/src/build/docs.rs
• SDK/package/generated output