--- title: "DropletPermission, DroppyKit" description: "Capability strings a .droplet declares under DroppyPermissions in its Info.plist." canonical: "https://getdroppy.app/docs/droppykit/api/droplet-permission" last-updated: "2026-09-09" --- # DropletPermission Capability strings a .droplet declares under DroppyPermissions in its Info.plist. `struct DropletPermission` Each value maps to a host facade, a TCC intent, or both. Review enforces the list: at runtime the host hands a droplet only the services its manifest declares, and review diffs declared capabilities against the symbols the bundle actually links. Honest caveat: in-process code can technically bypass Swift-level gating; the enforcement value is review plus store policy, not a sandbox. That is exactly why the store is review-and-sign rather than open sideloading. ## Open by design This is an open `RawRepresentable` struct rather than a closed enum, the same idiom as [`DropletID`](https://getdroppy.app/docs/droppykit/api/droplet-id), [`ShelfWidgetID`](https://getdroppy.app/docs/droppykit/api/shelf-widget-id) and [`ExpandedSurfaceID`](https://getdroppy.app/docs/droppykit/api/expanded-surface-id). Two reasons, and both are about time: - A bundle built against a newer SDK may declare a capability string this build has never heard of. An open type represents that string exactly rather than losing it, and the host treats anything it does not recognise as not granted. Before 0.3.0 the closed enum needed a separate `DropletBundleInfo.unknownPermissions` array to carry the leftovers. - Droplets compile DroppyKit as a non-resilient dependency, so a closed enum makes a missing `switch` case a compile error rather than an `@unknown default` warning. Adding a capability in 1.1 would have broken every droplet that switched on one. Because the type is open, `known` is the list this SDK build understands and is explicitly not exhaustive at runtime. Always write a `default:` when you switch. ## Initializers ### init(_:) `init(_ rawValue: String)` Creates a capability from a raw string. ### init(from:) `init(from decoder: Decoder) throws` ### init(rawValue:) `init(rawValue: String)` Creates a capability from a raw string. ### init(stringLiteral:) `init(stringLiteral value: String)` String-literal convenience, so `["hud", "media-read"]` reads naturally. ## Type properties ### accessibility `static let accessibility: DropletPermission` Use the Accessibility (AX) APIs. ### appleEvents `static let appleEvents: DropletPermission` Send Apple events / AppleScript. ### calendars `static let calendars: DropletPermission` Read and write calendars. ### camera `static let camera: DropletPermission` Use the camera. ### catalogActivate `static let catalogActivate: DropletPermission` Bring another droplet's surface forward. ### catalogCommands `static let catalogCommands: DropletPermission` List and invoke commands explicitly published by other products. ### catalogRead `static let catalogRead: DropletPermission` List the droplets and shelf widgets this host knows about. ### clipboardRead `static let clipboardRead: DropletPermission` Read the host's clipboard history as value snapshots. ### clipboardWrite `static let clipboardWrite: DropletPermission` Paste, rename, tag, pin, favorite and delete clipboard history entries. ### contacts `static let contacts: DropletPermission` Read contacts. ### documentSessions `static let documentSessions: DropletPermission` Read and edit a host-owned scoped document session. ### downloads `static let downloads: DropletPermission` Download and install auxiliary artifacts. ### entitlementsRead `static let entitlementsRead: DropletPermission` Read whether a gated host feature is active. ### expandedSurface `static let expandedSurface: DropletPermission` Take the expanded notch shelf over with droplet-supplied content. ### fullDiskAccessProbe `static let fullDiskAccessProbe: DropletPermission` Probe for Full Disk Access without requesting it. ### globalShortcuts `static let globalShortcuts: DropletPermission` Register global keyboard shortcuts. ### hostInteractionSuppression `static let hostInteractionSuppression: DropletPermission` Temporarily suppress one host interaction route with a revocable token. ### hud `static let hud: DropletPermission` Present transient HUDs. ### known `static let known: [DropletPermission]` Every capability this SDK build knows. **Not exhaustive at runtime.** A bundle built against a newer SDK may declare a string that is not in here, and that is a supported state: the host treats it as not granted and the droplet still loads. Use this to render a capability list or to split declared strings into known and unknown; never to validate a manifest closed. ### launcher `static let launcher: DropletPermission` Search and run Droppy's commands, settings, droplets and content from the droplet's own launcher ([`DropletLauncherService`](https://getdroppy.app/docs/droppykit/api/droplet-launcher-service)). Since 1.12.0. ### lockScreen `static let lockScreen: DropletPermission` Publish lock screen status entries. ### mediaRead `static let mediaRead: DropletPermission` Read now-playing state. ### mediaTransport `static let mediaTransport: DropletPermission` Drive media transport. ### menuBar `static let menuBar: DropletPermission` Contribute a menu bar extra, shown as a tile in Droppy's Command Center. ### microphone `static let microphone: DropletPermission` Record from the microphone. ### networkClient `static let networkClient: DropletPermission` Make outbound network connections. ### networkServer `static let networkServer: DropletPermission` Listen for inbound network connections. ### notchBanner `static let notchBanner: DropletPermission` Present banners on the host's notification surface. ### notchSurface `static let notchSurface: DropletPermission` Present expanded surfaces in the notch area. ### reminders `static let reminders: DropletPermission` Read and write reminders. ### screenCapture `static let screenCapture: DropletPermission` Capture the screen. ### shelfRead `static let shelfRead: DropletPermission` Read shelf items. ### shelfSurface `static let shelfSurface: DropletPermission` Drive the shelf window: keyboard focus, sizing, growth, drag handoff. ### shelfWrite `static let shelfWrite: DropletPermission` Add items to the shelf. ### soundPlayback `static let soundPlayback: DropletPermission` Play a semantic host-owned audible cue. ### speechRecognition `static let speechRecognition: DropletPermission` Transcribe speech with the system's speech recognizer. Request it through [`DropletPermissionsService`](https://getdroppy.app/docs/droppykit/api/droplet-permissions-service): the host answers `.unavailable` on a build that cannot prompt for it, where calling Speech directly would end the process. ## Properties ### description `var description: String { get }` ### isKnown `var isKnown: Bool { get }` Whether `known` contains this capability, meaning this SDK build understands it. ### rawValue `let rawValue: String` The raw capability string, as it appears in `DroppyPermissions`. ## Methods ### encode(to:) `func encode(to encoder: Encoder) throws`