Permissions and runtime safety

Two layers of permission

An Apsule Project first declares what it wants to use:

{
  "permissions": {
    "network": true,
    "storage": true,
    "bluetooth": true,
    "location": "whenInUse",
    "camera": false,
    "photos": false,
    "notifications": false,
    "liveActivities": false,
    "localNetwork": false,
    "music": false,
    "authentication": false,
    "weather": false,
    "translation": false,
    "nearbyInteraction": false,
    "spotlight": false,
    "wallet": false
  }
}

The Host shows the project's requested permission set before first run. A project update does not prompt again when the effective permission set is unchanged or reduced. If an update adds or broadens permissions, the Host must show only the newly requested/broadened access and require approval before those new permissions become usable. When an iOS-protected resource is actually requested, the normal iOS permission flow is still used.

The executable Host persists the approved permission set per project under its own Application Support container. Reductions are applied immediately and shrink the stored effective approval, so a permission removed by one revision must be approved again if a later revision re-adds it. An installed update may be accepted before the approval sheet is answered, but newly added/broadened Host API access remains denied and an automatic runtime reload is held until approval. Existing code may continue running with the previously approved effective permissions while that decision is pending.

Apsule project permission
        |
        v
Host API call
        |
        v
iOS system permission (when required)

Project permission never bypasses an iOS permission.

music: true gates all host.music.* APIs. The first MusicKit authorization still uses Apple's system consent flow. Apple Music provider/user tokens are kept inside MusicKit/Host and are never returned to Project JavaScript. The constrained host.music.api.request bridge fixes the destination to api.music.apple.com, rejects arbitrary URLs/path traversal, filters request headers, and therefore does not become a general authenticated HTTP proxy.

authentication, weather, translation, nearbyInteraction, spotlight, and wallet gate their matching Host API families. host.wallet.add additionally requires storage: true because the pass is read from the Project sandbox. Region/visit monitoring under host.location requires location: "always"; ordinary foreground location APIs continue to work with whenInUse.

Isolation

• Storage/database/keychain namespaces are project-specific.
• File writes default to a project sandbox.
• One project cannot directly read another project's sandbox.
• A future explicit Shared Container mechanism may allow selected projects to share selected data, but it must be opt-in and must not weaken the default isolation rule.
• Access to user files outside that sandbox requires an explicit picker/handle flow.
• A project may only call Host API families it declared and the user/Host allowed.
• Secrets should not be included in routine logs or runtime state dumps.

JavaScript runtime controls

The Host should plan for:

• execution time limits/watchdog;
• memory limits or practical guardrails;
• cancellation of runaway asynchronous work;
• cleanup of subscriptions on project stop;
• clear crash/error isolation so one project does not corrupt Project Manager state.

Stopping a project destroys its active JavaScript/runtime work (timers, live sockets, scans, watches and subscriptions), but it does not erase persistent project data. OS-managed work already committed to iOS may outlive the JavaScript runtime when the relevant Host API explicitly defines that behavior. Local notifications are the first intended example.

Network

Initial personal-use design may permit arbitrary HTTPS endpoints when network is granted. Keep the policy explicit so a future public distribution can tighten domains/transport rules without changing project semantics unexpectedly.

localNetwork is separate from Internet/network permission. It gates Bonjour discovery and direct TCP/UDP connections to LAN devices. iOS may additionally show the Local Network system prompt, and Bonjour browsing is limited to service types declared by the Host build.

Permissions and compatibility

Some iOS features require Info.plist usage descriptions, entitlements, App Services, background modes, or signing capabilities in the Host itself. A project declaration cannot add these dynamically. Runtime discovery reports code shipped by the installed Host; entitlement-dependent APIs must still fail explicitly when the current signature/profile cannot use them.

Apple Music is one example where Project permission alone is insufficient: the Host contains the usage description, the user must authorize MusicKit, and the App ID used for signing must have the MusicKit App Service enabled.

The same rule applies to platform-gated families such as WeatherKit, Sign in with Apple/passkeys, Nearby Interaction, NFC, HealthKit and HomeKit. Apsule intentionally does not force restricted entitlements into the default project because that would make ordinary development/sideload profiles fail to sign. The API stays discoverable when its implementation is present, but the call must report a runtime/platform error when the installed signature cannot use the Apple capability.