Minibar Capabilities and Permissions

Status v0.3 · for plugin authors and reviewers · Chinese original: 06-capabilities.md · API details: plugin-guide.en.md

Minibar is a platform. Every capability the host can obtain from macOS is meant to be available to plugins in a declared, granted and revocable form; conversely, the host never asks the system for anything no plugin has declared. This document spells both sentences out: the capability catalog, the permission and OS authorization behind each entry, how the host enforces least privilege, what is deliberately out of scope, and what comes next.

1. Five principles

2. Capability matrix

Status: ✅ shipped (v0.3) · 🗓 planned (milestone) · ⛔ never (§4)

3. Permissions in detail

network

• Only hosts in allowedHosts (plus subdomains), https only (localhost excepted), 15 s per request, 5 MB per response, 30 s of host waiting per render.
• "*" allows any host and is shown in red at install time; market review looks at it closely.
• Host entitlement: com.apple.security.network.client (no server).

clipboard

• Read: the first read in each app session is confirmed once more on the card (PRD F-45), then not again that session; revoking the permission takes effect immediately.
• Write: action only, text up to 100 KB. Writing needs no session confirmation (nothing leaks).

notifications

• One per plugin per 60 seconds; the system authorization is requested on the first post; when turned off at the system level the notification is dropped and logged.

calendar / reminders

• Read only; on macOS 14+ full access is requested (EventKit's only readable tier). The first call triggers the system prompt; while it is up the plugin gets os_access_pending and the host re-renders once the user answers.
• Writes only from an action (the user tapped a button): calendar.add() creates an event, reminders.add() a reminder, reminders.complete(id) ticks one off (or reopens it). Only calendars and lists that allow modification; titles ≤ 200 characters, notes ≤ 2000, events ≤ 1 year long; no deleting, no bulk edits, no changes to other people's events. The bundled Reminders plugin uses complete so the user can tick reminders off right in the menu bar.

location

• 1 km accuracy, 15-minute cache, reverse-geocoded city name. First call triggers the prompt, same flow as above.

system

• freeMemory(): the host allocates and touches up to half of physical memory for at most 3 seconds so the kernel reclaims cached and inactive pages, then releases it; stops early when free pages run low. Returns free bytes before and after.
• runShortcut(name, input?): runs a Shortcut the user created through shortcuts://run-shortcut. This is the general-purpose channel to the rest of the system (open apps, control HomeKit, call any service); the boundary is whatever the user put in the shortcut.
• keepAwake(enabled): IOPMAssertionCreateWithName prevents idle sleep; one assertion per plugin, released automatically when the plugin is disabled, loses the permission, is uninstalled, or the app quits.
• All three are action-only.

apps

• apps.running(): name, bundle ID, frontmost and hidden flags of regular (Dock-visible) apps. No window titles, no process arguments.
• apps.open(bundleID): opens or activates an installed app; unavailable when it is not installed.
• allowedSchemes: URL schemes declared in the manifest (things, obsidian, raycast…) are the only ones ctx.openURL("things:///add?title=…") lets through; undeclared schemes are refused. http/https/mailto are always allowed; file/javascript/data never.

files

• A plugin never gets read access to a path; it gets what the user picked by hand in the system file dialog: ctx.files.pick({ folders, multiple, types, message }) is action-only and returns at once. The host shows the dialog, names the plugin that is asking, stores a security-scoped bookmark for each chosen item and re-renders the plugin.
• Afterwards, in any phase: list() (picked items, with available false for moved or deleted ones), entries(id) (direct children of a picked folder, hidden files skipped by default, ≤ 500), read(id, { encoding, maxBytes }) (≤ 1 MB, the rest flagged truncated). Children are addressed as "<id>/<relative path>"; .., absolute paths and symlinks that leave the folder are rejected.
• All reads happen inside the app's sandbox scope; the XPC runtime process never touches the file system. Content reaches the plugin as a JSON string.
• Revocation: the plugin can forget(id); the user removes items one by one or all at once under Settings › Plugins › "Files this plugin can read"; switching files off clears everything; uninstalling removes the record. At most 50 items per plugin, newest kept.
• Not offered: writing, creating, deleting, watching folders, walking the home directory (anything the user did not pick is invisible).

4. Deliberately out of scope

5. How the host enforces least privilege

5.1 Entitlements (static minimum, locked by CI)

Tests/MinibarCoreTests/EntitlementsTests.swift asserts that these two files contain exactly these keys; a new capability must change the test and this table together.

5.2 System prompts only on first use

Onboarding only records plugin-level grants; its last page says that macOS may ask once when a plugin first uses a capability.

5.3 Revocation and cleanup

After a permission is revoked both checks apply immediately (no restart); revoking system or disabling / uninstalling a plugin releases its wake assertion; revoking clipboard also clears the session confirmation. Uninstalling removes the plugin's storage and settings.

5.4 For reviewers

• The complete interface available to plugins is §2; there is no hidden channel. __host accepts strings only and permissions are checked in the bridge and again in the app process.
• Every side effect needs a tap; every system prompt needs a prior plugin-level grant.

6. Guidance for plugin authors

1. Declare only what you use and explain it in description; the install prompt shows it verbatim.
2. Degrade gracefully: render something without grants. Use ctx.permissions.granted('location') to choose a branch; catch permission_denied and offer a $allow:<permission> button so one tap grants it.
3. While a system prompt is up (os_access_pending) do not retry in a loop; the host re-renders when the user answers.
4. Side effects go in actions: button → action → ctx.openURL / apps.open / clipboard.write / freeMemory / runShortcut / keepAwake.
5. URL schemes must be listed in allowedSchemes and need the apps permission.
6. No secrets in code: use a secret setting and ctx.settings.get(); the host keeps it out of logs.

7. Roadmap