Extension API & runtime

NextGuide is growing beyond content-only add-ons. Future extensions can provide React/MDX UI, themes, languages, admin tools, AI providers, authentication integrations and server functionality. Not all of these are executable today.

Runtime foundation

The single nextguide package now exposes these building blocks:

All exports are part of one npm package, not additional packages to install. See Getting started for the currently publishable v1 format.

Permissions and lifecycle

An add-on declares capabilities such as mdx.blocks, ui.components, admin.pages, storage.read, storage.write, network.fetch or server.routes. The host grants only capabilities approved by the site owner. Unsupported operations remain disabled even when an add-on declares them.

The initial trusted lifecycle host supports registration, explicit approval, activation, deactivation, cleanup and data-only contributions. That registerTrusted() API is only for site-owner-controlled code. It must never receive registry JavaScript directly.

Capability broker

An isolated runner will communicate with the host through typed JSON messages. The broker accepts a verified manifest and an artifact SHA-256; the site must provide its own trusted authorization callback that verifies the signed release and stored owner permission grants.

import { createExtensionBroker } from "nextguide/extensions/runtime"
import { createExtensionFileStorage } from "nextguide/extensions/storage"

const broker = createExtensionBroker({
  // Application-owned security check. Do not accept grants from the add-on.
  authorize: verifySignedInstallAndOwnerApproval,
  storage: createExtensionFileStorage("/private/nextguide/extension-storage"),
})

// The runner transport remains a separate, future isolation component.
const session = await broker.openSession(verifiedManifest, pinnedSha256)
const reply = await session.handle({
  id: "request-1", method: "storage.get", params: { key: "preferences" }
})
session.close()

verifySignedInstallAndOwnerApproval, verifiedManifest and pinnedSha256 are host application inputs, not exports supplied by NextGuide. The example illustrates the interface; a complete secure installer is not yet available.

The broker currently implements:

By default, there is no network adapter, no arbitrary filesystem access, no secret read method and no script-execution method. A trusted host may explicitly configure nextguide/extensions/network to enforce exact permitted HTTPS hosts, block private or reserved DNS addresses, pin one approved IPv4 address for the TLS connection, reject redirects and cap JSON responses. The broker still enforces each individual extension's approved network host list. Do not expose the adapter directly to extension code.

Persistent storage limits each key to roughly 32 KiB and each extension to 128 keys / 1 MiB. It must live outside the served Next.js directories, under an owner-controlled private path.

Restrict outbound HTTPS

A verified add-on can request network access only when both its permissions and the trusted host's HTTPS adapter allow the destination. The adapter is IPv4-only for now and rejects an entire DNS answer if even one returned IPv4 address is private or reserved. It does not follow redirects and requires valid TLS certificates for the original hostname.

import { createRestrictedExtensionHttpsAdapter } from "nextguide/extensions/network"

const network = createRestrictedExtensionHttpsAdapter({
  allowedHosts: ["api.example.org"],
  timeoutMs: 8000,
})

// Pass network to createExtensionBroker only in trusted host code.

This is a host capability adapter—not an executable extension sandbox. Host operators should additionally enforce egress restrictions at the OS/network layer.

Verify approved content archives safely

The nextguide/extensions/artifacts export checks currently publishable v1 Markdown archives before installation. It requires the original Ed25519-signed catalog envelope, a site-pinned public key, the exact requested add-on ID/version and the downloaded archive bytes.

It rejects revoked versions, invalid signatures, size or SHA-256 mismatches, malformed gzip/tar headers, symlinks, traversal paths, duplicated or case-colliding filenames, executable members, invalid PNG icons and excess file counts. Verification returns Markdown strings and icon bytes in memory—it neither writes to disk nor installs anything.

The downloader is intentionally separate: the site must only retrieve the reviewed GitHub Release artifact using a trusted transport, with redirect and network restrictions. The verifier is the byte-level integrity gate, not an HTTP downloader.

Private Account Mode installation journal

The single package also provides nextguide/extensions/install-state to trusted server code. It stores reviewed content-only v1 releases under the Account Mode private data directory (outside the Next.js project). Archive files are named by their SHA-256 and retained immutably; one atomic index tracks installed versions and a revision used to reject concurrent changes.

The journal exposes install, setEnabled, rollback, uninstall, list, and readEnabled. It verifies the original signed registry envelope, the exact archive hash, release approval, compatibility and the registry's signed timestamp. By default an installed release is disabled. Rollback always leaves it disabled until the owner explicitly enables it again. Uninstall leaves private add-on settings intact, with cleanup to be added separately.

Security constraints:

• Only Account Mode may create the journal; Developer Mode is rejected.
• An enabled release is still data-only Markdown. It must never execute scripts, MDX expressions or untrusted HTML.
• Activating or reading a release rechecks its signed status and locally stored digest; revoked or stale releases fail closed. The registry must refresh its signed index at least hourly for state changes to succeed.
• The Account Mode dashboard now includes the reviewed v1 downloader and installation actions. A generated public route serves only explicitly enabled, still-approved Markdown, rendered as safe React text—not executable MDX. Sidebar/search integration and privileged v2 extensions remain separate milestones.
• Explicit browser consent and permission diffs remain required for future executable v2 add-ons.

Fetch approved archives without arbitrary redirects

nextguide/extensions/download provides a Node-only downloadVerifiedContentRelease helper for content-only v1 packages. It authenticates the original signed catalog envelope, requires an active reviewed GitHub Release and downloads its exact versioned artifact.

The downloader uses HTTPS with server certificate verification and pins a validated public IPv4 DNS answer to the socket. Redirects are accepted only to dedicated GitHub release-asset CDN hostnames; it will not send credentials, follow arbitrary URLs, allow proxies, or accept private/reserved DNS answers. It enforces byte limits, response length, a timeout and abort, and re-verifies the entire archive content and SHA-256 before returning bytes.

This helper does not install the archive. Call the Account Mode private installation journal only after its own owner-authentication, permission approval, current NextGuide version compatibility, signed registry freshness and atomic state checks. A reviewed .tgz must never be executed as code.

Linux isolated execution (prototype)

The Node-only nextguide/extensions/isolation export can launch a single compiled ES module out of process. It checks the exact UTF-8 SHA-256, opens a separately authorized capability-broker session, and communicates through size-bounded JSON lines. It does not execute unsigned archive contents, installer scripts, or arbitrary filesystem paths.

The host requires a non-root Linux user, Bubblewrap and util-linux prlimit. The runner explicitly requires new user, PID, network, IPC and UTS namespaces. Only a read-only extension module, the confined worker, host runtime libraries and private temporary storage are mounted. Permitted HTTPS calls must pass through the host's broker. Startup, CPU time, virtual address space, descriptors, IPC output and total lifetime are bounded, but cgroup memory and process-count quotas are still missing.

sudo apt-get update
sudo apt-get install bubblewrap util-linux

This is an internal integration prototype, not the end-user marketplace installation API. A trusted Account Mode host must authenticate the site owner, verify the approved release bytes, signature and grants, and construct the broker before running this module. A third-party compiled module exports an activate function that receives only a bounded JSON request bridge. Never pass an unreviewed download or add-on-supplied policy into the launcher.

Windows deployments reject executable add-ons rather than falling back to ordinary child processes, Node workers or node:vm. Linux hosts without working Bubblewrap/user namespaces also reject them. Signed v2 archives, full platform resource isolation, browser-side React widgets, host integration, install/update/rollback and production acceptance remain separate work. Do not enable executable public marketplace add-ons yet.

Render add-on UI without importing its code

The first UI pathway is a declarative view tree rendered by NextGuide. The host only accepts supported node kinds such as headings, text, cards, stacks, badges, links and action buttons.

import { ExtensionView } from "nextguide/extensions/ui"

const descriptor = {
  type: "card",
  children: [
    { type: "heading", level: 2, text: "Search settings" },
    { type: "button", text: "Configure", action: "open_settings" },
  ],
}

<ExtensionView view={descriptor} onAction={action => {
  // Handle through the host's permission-checked action dispatcher.
}} />

The renderer does not support arbitrary HTML, JSX, injected React components, scripts or untrusted URL schemes. A future isolated UI runtime will be necessary for add-ons that need custom React code. Button actions are identifiers; the host application must authorize them before performing mutations.

Trust the signed catalog, not unsigned JSON

The Node-only nextguide/extensions/catalog client validates the Ed25519 signature and uses a pinned public key supplied by the installed NextGuide application. The key must not be downloaded from the same response it is intended to authenticate. The client checks the signed release metadata, rejects incorrect artifact URLs and digests, and excludes revoked versions from new installations.

The public API is read-only; it does not download or execute package content. A future installer must verify the exact downloaded artifact SHA-256 and recheck revocation/permissions before activation. The registry index is signed for integrity but currently does not provide an expiry timestamp, so freshness and revocation propagation need additional policy before general availability.

Next milestones

1. Harden the isolated runner: Real Linux validation, cgroup resource quotas and an independent security review; provide a Windows isolation backend or preserve explicit unsupported-mode refusal.
2. Host services: Secure DNS-pinned network adapter, namespaced credential handles, server route and job dispatch, scoped data storage and quotas.
3. Browser UI isolation: Signed asset delivery, sandboxed views for code-capable React widgets, and controlled host messaging.
4. Private registry verifier: Independently inspect and approve v2 executable releases and permission changes. The private ngapi service is deployed separately.
5. Account Mode marketplace: Signed catalog browsing, installation, permissions, activation, updates, rollback and uninstall.

Legacy v1 Markdown add-ons stay supported, but are not the limit of NextGuide's add-on architecture.

Create a content add-on · Publish and review

Add-on documentation home · Permissions & security · Marketplace (planned)