Plugin Permissions

Plugin Permissions

Permissions describe the host capabilities a plugin requests and the boundaries that remain around those capabilities.

Read a permission request

Before installing, compare the requested access with the plugin's job. Reading a selected molecule is different from reading the whole document; displaying analysis is different from inserting objects. Package review displays the declarations and highlights permissions in the SDK's dangerous list. Available declarations are granted as part of installation, without individual permission toggles.

A declaration alone does not promise a general-purpose API. The command context exposes specific typed services. There is no arbitrary shell service for native.execute, and the desktop currently refuses packages declaring network.fetch because its external-network broker is not available. Installed workers also have a Content Security Policy, a browser-enforced restriction on code and network loads, that limits access to their own origin.

Permission reference

“Dangerous” below follows dangerousPluginPermissions in the SDK. “No” means absent from that classification, rather than universally harmless. Several names reserve capabilities without exposing a corresponding general-purpose method today.

Permission	Dangerous	Meaning and current boundary
document.read	No	Read an immutable active-document copy; also required for document-aware SMILES layout.
document.write	Yes	Insert through command-scoped documents.applyPatch; no unrestricted editing.
document.proposePatch	No	Queue a patch for the user's review.
selection.read	No	Read selected object IDs and molecule snapshots.
selection.write	No	Declared permission name; no general selection-write method on the command context.
analysis.write	No	Write session analysis and read this plugin's own records.
ui.panel	No	Show declared reports and use the host-owned text prompt.
ui.toolbar	No	Contribute toolbar buttons or toolsets through the runtime.
ui.menu	No	Contribute command-backed menu entries.
chemistry.compute	No	Request host chemistry services, with additional gates for some methods.
clipboard.read	Yes	Declared name; no general clipboard-read context method.
clipboard.write	No	Declared name; no general clipboard-write context method.
image.read	Yes	Acquire a user-chosen image during the plugin's command; no arbitrary image-file or whole-screen access.
ml.inference	No	One of the four permissions required for local recognition.
model.load	Yes	One of the local-recognition gates; no general model-loading context method.
model.download	Yes	Declared name; recognition plugins must not request it. The host owns engine installation.
filesystem.read	No	Declared name; no general filesystem-read context method.
filesystem.write	Yes	Declared name; no general filesystem-write context method.
network.fetch	Yes	Reserved and currently refused by the desktop.
native.execute	Yes	Additional gate for process-backed host services; no plugin-selected native execution API.
plugin.storage	No	Plugin-scoped key/value storage through get, set, delete, and listKeys.

Although the project distinguishes user-chosen image input from broader image access, the current SDK marks the image.read name itself dangerous. Do not interpret that classification as a grant of broader image access.

Some methods need several permissions

Host method	Required declarations
chemistry.isotopeEnvelope	chemistry.compute
chemistry.nameToStructure	chemistry.compute, native.execute
chemistry.structureFromSmiles	chemistry.compute, document.read
chemistry.structureToName	chemistry.compute, native.execute, selection.read
recognition.recognizeStructure	image.read, ml.inference, model.load, native.execute

OPSIN needs native.execute because the host starts its Java process. Layout needs document.read because the generated object's ID and coordinates depend on the document. A chemistry permission cannot bypass either boundary.

Direct writes and reviewed proposals

document.write works only during one of the declaring plugin's own command invocations. It accepts insertions using addObject or addAnnotation, refusing replacement, removal, and other editing operations. The host commits one labelled undo entry and selects inserted objects. Switching to a different document while the command runs causes the direct write to be refused.

Use direct insertion for deterministic user-supplied input. Inferred results and changes to existing content go through documents.proposePatch. Image recognition always requires review. The host refuses a plugin declaring all four recognition permissions together with either document.write or model.download.

Image, prompt, and report boundaries

images.requestImage and dialogs.promptText are command-scoped. A retained reference does not extend their lifetime. A command can show at most one text prompt to the user; cancellation also consumes that allowance and returns a cancelled result. Image recognition accepts only the unmodified image the host supplied during that same command.

Reports are host-rendered data. The chemicalName section supplies a host Copy button, so showing a name does not require a clipboard declaration. Desktop result windows themselves receive no filesystem, dialog, or clipboard capability; privileged actions are routed through the document window.

These boundaries are shared contracts on macOS and Windows. Their native menus and window behavior differ as described in macOS and Windows Differences.

Next

• Install and review a package
• Full plugin API reference
• Write a least-privilege plugin