How requested capabilities, explicit approval and signed registry releases work.

Permissions & security

NextGuide's extension API separates what an add-on requests from what a site owner approves. A manifest is not a sandbox, a code signature is not an execution grant, and an add-on cannot grant itself new privileges.

The capability model

Capability	Intended scope
`docs.pages`, `mdx.blocks`	Contribute documentation content and MDX blocks
`ui.components`, `admin.pages`	Display custom UI and dashboard tools
`theme.tokens`, `icons.packs`, `i18n.locales`	Appearance and translations
`ai.providers`, `auth.providers`	Host-mediated AI and authentication integrations
`storage.read`, `storage.write`	Namespaced extension storage
`network.fetch`	Controlled host-side outbound requests
`server.routes`, `server.jobs`	Future isolated server endpoints and tasks
`secrets.read`	Reserved capability; not currently exposed as a broker method

Declaring permissions is not approval

Draft v2 manifest capabilitiesJSON

{
  "schemaVersion": 2,
  "id": "acme.search-tools",
  "name": "Search Tools",
  "version": "1.0.0",
  "category": "integration",
  "compatibility": {
    "mode": "account",
    "nextguide": ">=1.0.0 <2.0.0"
  },
  "permissions": [
    "admin.pages",
    "storage.read",
    "storage.write"
  ],
  "entrypoints": {
    "server": "dist/server.mjs",
    "client": "dist/client.js"
  }
}

The current trusted host requires explicit owner approval before activation. The future marketplace must ask the owner again when a newer release requests additional permissions.

Owner activity and registry outages

Account Mode stores a private, bounded journal of the latest 100 successful add-on installation changes, including installs, enabling, disabling, upgrades, rollbacks and removals. Each event records the add-on ID, version, change type, UTC timestamp and installation revision. The journal is committed atomically with the installation state, so denied and interrupted transactions cannot create misleading success events.

The owner can review recent activity under Admin → Add-ons. This journal contains no downloaded executable code, access tokens or signing keys; it is local operational history, not a substitute for independent code review or security monitoring.

When a configured registry cannot be verified, the catalog fails closed and shows no releases. Owners can still inspect their local installed list and activity history, disable content or uninstall it; installation, upgrading and enabling remain blocked until a fresh signed catalog becomes available.

Host-mediated messages

The nextguide/extensions/runtime broker binds messages to an already verified add-on identity. Client-supplied IDs cannot switch storage namespaces. Network requests are denied by default. The optional restricted HTTPS host adapter pins vetted public IPv4 DNS results to a TLS connection, rejects redirects and has fixed response limits. It must be configured by the trusted host and never exposed directly to add-on code.

Example broker requestJSON

{
  "id": "request-1",
  "method": "storage.get",
  "params": {
    "key": "preferences"
  }
}

Isolation is still required

The broker is a permission enforcement component, not a secure JavaScript sandbox. Executable packages need OS/browser isolation and signed artifact verification before they can run. Neither bare Node worker threads nor in-process import() provide the required trust boundary.

Learn more in the Extension API and the security roadmap.