Permissions

Extensions declare the capabilities they need in their manifest. Users approve them at install time; some sensitive operations additionally prompt at runtime. Enforcement always happens in the host — never in your plugin code.

Two forms of permission

Simple — a capability with no scope:

{ "kunkun": { "permissions": ["clipboard-read", "storage", "notifications"] } }

Scoped — an object with an allow/deny list or domain list:

{
  "permission": "fs-read",
  "allow": ["$EXTENSION_SUPPORT/**", "$HOME/Documents/**"],
  "deny": ["$HOME/Documents/Private/**"]
}

Permission catalogue

Path aliases

Scopes use cross-platform aliases resolved by the host:

Globs: ** (recursive), * (one level), *.ext (extension match).

Runtime (dynamic) grants

Some capabilities are best requested just before you need them, scoped to what the user is doing:

import { permissions } from "@kunkunsh/sdk";

const granted = await permissions.request(
  "fs-read",
  "$HOME/Documents/**",
  "Import the files you selected",   // shown in the prompt
);
if (granted) { /* … */ }

• Allow Once → stored in a session map, cleared when the window closes.
• Always Allow → persisted in the permission_grants table, user-revocable in settings.
• Deny → returns false.

permissions.check(type, scope) is a preflight query — not an authorization boundary. Always let the host enforce.

How enforcement works

Notice scoped filesystem checks resolve symlinks before matching, so a symlink can't smuggle access outside your allow-list.

Service permission intersection

When extension A calls extension B's service, the effective permissions compose safely:

• Caller resource permissions (fs, network, open-*) for user-chosen resources are preserved.
• Provider implementation permissions (e.g. the provider's scoped shell access to ffmpeg) are supplied by the provider, so callers don't have to declare the provider's private details.
• Everything else requires both sides.

This prevents privilege escalation: a low-permission extension can't gain capabilities by calling a high-permission service.

Raycast compatibility policy

Imported Raycast extensions run under a stricter policy. Each host method is tagged raycast-allowed or kunkun-only; Kunkun-only APIs (e.g. shell.spawn) are rejected for Raycast-sourced plugins even if the namespace is imported. Native Kunkun extensions get the full surface (still subject to manifest permissions).

Process sandbox

For Node modes and backends, the host derives runtime flags from your manifest:

Your install directory is read-only; your support directory is writable. See Backend Processes for spawning managed child processes.

Checklist

• Request the minimum permissions; scope filesystem/network tightly.
• Use $EXTENSION_SUPPORT for your own data.
• Request sensitive scopes at runtime with a clear reason.
• Handle denial gracefully — check before acting, degrade rather than crash.
• Document why you need each permission in your README.