Permissions
You ask in the manifest for what your extension may use; the user approves.
An extension can only use the APIs it asks for in the permissions array of manifest.json and the user approves. The user sees the list when installing the extension and can turn permissions off later in Settings › Extensions.
"permissions": ["system.stats", "media.read", "network:api.github.com"]Calling an API, or subscribing to an event, without its permission throws a PermissionError. Handle turned-off permissions gracefully:
try {
const track = await AdanotchKit.media.nowPlaying();
} catch (error) {
if (error instanceof PermissionError) {
return { expanded: ui.text("Media access is off", { tone: "secondary" }) };
}
throw error;
}The list
| Permission | What it opens |
|---|---|
system.stats | system.stats(): CPU %, RAM %, memory in GB |
battery.read | battery.read(), the battery.change event |
notifications | notify.island({ text, icon, tone, duration }) |
media.read | media.nowPlaying(), the media.change event |
media.control | media.play(), pause(), toggle(), next(), previous(), seek() |
calendar.read | calendar.events({ days }) (1–31 days, default 1), the calendar.change event |
reminders.read | reminders.today(), the reminders.change event |
clipboard.read | clipboard.readText(), the clipboard.change event |
clipboard.write | clipboard.writeText(text) |
network:<domain> | fetch to that domain and its subdomains, redirects, and ui.image |
No permission needed: system.isOnline(), system.appearance(), storage, secrets, island, open(), render, timers, and the network.change, system.wake, system.sleep, appearance.change and command events.
Network permissions
network:api.github.com covers api.github.com and *.api.github.com; it doesn't cover github.com. List every domain:
"permissions": ["network:api.github.com", "network:avatars.githubusercontent.com"]- Only
https://URLs are allowed. - Redirects follow the same list; a request redirected to a domain not on it ends with a
PermissionError. ui.imageshows images from these domains only.- Ask whether a URL can be fetched with
ctx.network.isAllowed(url).
macOS permissions
Some APIs also need Adanotch itself to have a macOS permission:
- Calendar and Reminders: Adanotch must have access in System Settings › Privacy & Security. Without it,
calendar.events()andreminders.today()throw aPermissionError. - Media: Adanotch's Music module must be on; the extension reads what it sees.
Ask for little
adanotch lint warns about permissions you ask for but don't seem to use, and about domains in your code that have no network: permission. Users see every permission you ask for.