Permissions and networking
Consent, destinations, private addresses and structured errors
Declare permissions as { name, purpose? } entries in notyra.permissions. The developer-supplied purpose is displayed literally beside Notyra's own permission explanation.
| Permission | Required by |
|---|---|
notes:read | notes.listRootFolders, list, read |
notes:write | notes.create, update, rename, move, delete |
clipboard | clipboard.readText, writeText |
shell:openExternal | shell.openExternal |
network | network.fetch; also requires declared destinations |
CSS, panels, Markdown, editor extensions, commands, keys, settings and active-note events need no permission. Missing permission rejects with permissionDenied before invoking the operation. Installation always asks for consent, even for zero permissions. Updates request consent for added permissions/destinations and remove revoked declarations from the stored consent.
Destination syntax
Examples: api.example.com, *.example.com, localhost:11434, 192.168.1.10:8080, [::1]:3000. Do not include a URL scheme, path or credentials. Ports are 1–65535. A declaration without a port matches only effective ports 80 or 443; an explicit port matches exactly that port. Host names are case-insensitive.
*.example.com matches a.example.com and a.b.example.com, but not example.com itself. IPs are compared by value. Only the exact host name localhost is Private; foo.localhost and wildcard names are Public.
Private ranges are 0.0.0.0/32, ::/128, 127.0.0.0/8, ::1, RFC1918 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, link-local 169.254.0.0/16, fe80::/10, and IPv6 unique-local fc00::/7. IPv4-mapped IPv6 addresses are classified as IPv4. CGNAT 100.64.0.0/10 is Public.
A Public name resolving to any Private IP, including unspecified addresses, is blocked before sending. localhost resolving outside Private ranges is also blocked. Connections are pinned to the checked addresses; every redirect is rechecked.
Only HTTP/HTTPS is supported, with at most 10 redirects, a 30-second per-request deadline covering DNS through body receipt, and a 10 MiB response limit. Proxies are disabled. Host and connection-control headers cannot be overridden. A command that starts a longer request must also account for the host's separate 10-second command timeout.
Errors
kind | Meaning |
|---|---|
permissionDenied | Required permission is absent; details may include backend permission information |
schemeNotAllowed | Not http/https for network, or not http/https/mailto for external links |
blocked | Undeclared host/port, redirect or DNS classification violation |
outOfScope | Note path is outside registered roots |
notFound / nameConflict | Missing note or an occupied rename target |
deleteRejected | User cancelled deletion |
timeout / tooManyRedirects / responseTooLarge | Network time, redirect or response-size limit |
network / io | Network or filesystem failure |
invalidArgument / pluginNotActive | Invalid argument or a call after stopping |
Backend details for blocked contain host, port, and a reason: notDeclared, redirectNotDeclared, resolvedToPrivate or resolvedToNonPrivate. Do not silently swallow failures; show actionable errors in your UI where needed.
Permissions gate the API; they are not a complete sandbox isolating arbitrary third-party JavaScript. Use trusted sources and keep secrets out of plugin source and release ZIPs.