Building Plugins

Community plugin directory

Search the directory below, then use Install in Moldavite to open the app directly on that plugin. Moldavite fetches the registry because you clicked the install link, shows the permissions before installation, and asks Rust to verify both SHA-256 hashes before the shared staged installer makes files visible. A newly installed plugin stays disabled until you grant its permissions. Changed files always require a fresh grant. You can also browse from Settings → Plugins.

No plugins match that search. Try a name, author, or permission such as notes.read.

Trust boundary

Each plugin executes as an ES module in its own Web Worker with no DOM, Zustand, and no raw Tauri IPC. Before plugin code is evaluated the worker scope is reduced to an allowlist: the language built-ins, console, timers, crypto, text encoding, URL, Blob, and the postMessage channel. Everything else is gone: fetch, XMLHttpRequest, WebSocket, EventSource, importScripts, nested workers, caches, indexedDB, and WebAssembly among them. Because it is an allowlist, capabilities shipped by future browser capabilities begin denied and remain outside the sandbox until they are allowlisted. Network access goes through the permissioned net.fetch method.

The worker proxy rejects undeclared calls early for useful errors, but Moldavite repeats permission and argument checks in the host. The host check is the security boundary. Unknown RPC methods are rejected.

Quick start

Create a folder under the active Forge with exactly this shape:

<Forge>/.plugins/my-plugin/
├── manifest.json
├── plugin.js
└── README.md          # optional, recommended for distribution

1. Make the folder name match the manifest id.
2. Add a current manifest and a default register(api) export.
3. Open or reopen Settings → Plugins.
4. Enable the plugin and review the permission sheet.
5. Run its commands from ⌘ P or the editor slash menu.

There is no build or package requirement. A dependency-free plugin.js works as written. If you bundle dependencies, distribute the final self-contained ES module because Moldavite loads only that one entry file.

Manifest

{
  "id": "my-publisher",
  "name": "My Publisher",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "Publishes the active note to an approved service.",
  "apiVersion": 2,
  "minAppVersion": "1.6.0",
  "permissions": [
    "editor",
    "ui",
    "notes.read",
    "net.fetch",
    "secrets"
  ],
  "allowedHosts": ["api.example.com"],
  "commands": [
    { "id": "configure-publisher", "label": "Configure publisher" },
    { "id": "publish-note", "label": "Publish active note…" }
  ],
  "instructions": [
    "Enable the plugin and approve its permissions.",
    "Press `Cmd+P` and run **Configure publisher** first.",
    "Open a note, then run **Publish active note…**."
  ]
}

Unknown top-level fields and incorrectly typed values invalidate the manifest. Host matching is exact. A grant for api.example.com covers only that hostname and its default port. The permission sheet displays every manifest host.

Every successful in-app install opens a themed About this plugin dialog from this validated metadata, and the installed card's ⓘ button reopens it at any time. Without instructions, Moldavite generates a short enable-and-palette flow from the description and command list. Legacy manifests remain compatible and use runtime-registered commands as a display fallback after enable.

Entry point and command lifecycle

plugin.js is an ES module whose default export receives the API. Register commands during startup; command handlers may be synchronous or asynchronous.

export default function register(api) {
  api.commands.add({
    id: 'inspect-active-note',
    label: 'Inspect active note',
    handler: async () => {
      const note = await api.editor.getActiveNote();
      if (!note) return;
      await api.ui.toast(`Open: ${note.path}`, 'success');
    },
  });
}

Moldavite namespaces command ids as <plugin-id>:<local-id> in the host. Keep local ids stable and unique within the plugin. Every API call except commands.add is an asynchronous RPC. A command invocation that never settles is rejected by the host after 30 seconds.

Complete Plugin API reference

interface PluginAPI {
  app: { version: string; apiVersion: 2 };

  commands: {
    add(command: {
      id: string;
      label: string;
      handler: () => void | Promise<void>;
    }): void;
  };

  editor: {
    getActiveNote(): Promise<{
      path: string;
      title: string;
      content: string; // editor HTML
    } | null>;
    insertText(text: string): Promise<void>;
  };

  ui: {
    toast(
      message: string,
      kind?: 'info' | 'success' | 'error'
    ): Promise<void>;
    prompt(options: {
      title: string;
      message?: string;
      fields: Array<{
        name: string;
        label: string;
        type: 'text' | 'password' | 'url';
        placeholder?: string;
        required?: boolean;
      }>;
      confirmLabel?: string;
    }): Promise<Record<string, string> | null>;
  };

  notes: {
    list(): Promise<Array<{
      path: string;
      title: string;
      kind: 'daily' | 'weekly' | 'standalone';
      folder: string | null;
    }>>;
    read(path: string): Promise<string>; // Markdown body
  };

  net: {
    requestHostAccess(host: string): Promise<boolean>;
    fetch(url: string, options?: {
      method?: string;
      headers?: Record<string, string>;
      body?: string;
    }): Promise<{
      status: number;
      headers: Record<string, string>;
      bodyText: string;
      bodyBase64?: string;
    }>;
  };

  secrets: {
    get(key: string): Promise<string | null>;
    set(key: string, value: string): Promise<void>;
    delete(key: string): Promise<void>;
  };
}

App and commands

if (api.app.apiVersion !== 2) throw new Error('API v2 required');

api.commands.add({
  id: 'hello',
  label: 'Say hello',
  handler: () => api.ui.toast(`Hello from Moldavite ${api.app.version}`),
});

Editor

const active = await api.editor.getActiveNote();
if (active) {
  console.log(active.path, active.content); // content is HTML
  await api.editor.insertText('\nPublished from Moldavite.');
}

Key per-note state with path, since display titles can change. The current API has no general note-write method. insertText is an explicit active-editor action under the editor permission.

User interface

await api.ui.toast('Ready to publish', 'success');

const values = await api.ui.prompt({
  title: 'Configure publishing',
  message: 'Credentials are verified before saving.',
  fields: [
    { name: 'site', label: 'Site URL', type: 'url', required: true },
    { name: 'password', label: 'Application Password', type: 'password', required: true },
  ],
  confirmLabel: 'Verify and save',
});
if (!values) return;

The host allows one plugin prompt or host-consent dialog at a time and always displays Request from plugin: Plugin Name in trusted chrome above plugin-controlled copy. A form has 1–12 fields. Field names must be unique identifiers beginning with a letter; supported field types are text, password, and URL. Titles are limited to 200 characters, messages to 2,000, confirm labels to 80, names to 64, labels to 160, and placeholders to 300.

Notes

const notes = await api.notes.list();
const standalone = notes.find((note) => note.kind === 'standalone');
if (standalone) {
  const markdownBody = await api.notes.read(standalone.path);
  await api.ui.toast(`Read ${markdownBody.length} characters`);
}

Paths are Forge-relative, such as daily/2026-07-13.md or notes/Projects/roadmap.md. The list's folder is relative to notes/ for standalone notes and null otherwise. The read result is the parsed Markdown body; YAML frontmatter is not included. The plugin receives no arbitrary filesystem-read capability.

Network and runtime host consent

const site = new URL('https://notes.example.com');
const approved = await api.net.requestHostAccess(site.hostname);
if (!approved) return;

const response = await api.net.fetch(`${site.origin}/api/drafts`, {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ title: 'From Moldavite' }),
});
if (response.status >= 400) throw new Error(response.bodyText);

requestHostAccess uses the manifest hostname validator: no scheme, port, path, wildcard, IP literal, single-label name, or label named localhost. The consent dialog names the plugin and exact host. Existing manifest or runtime approval returns true without another prompt.

Runtime approval is stored in Moldavite's per-Forge plugin grant record, outside the plugin files. The effective allowlist is the union of manifest and user-approved hosts. Users can revoke a runtime host under Settings → Plugins → View permissions; the next request and every redirect hop immediately use the reduced union.

Fetch validation and redirect policy

• URLs must be absolute HTTPS without embedded username or password.
• Request methods contain letters only; CONNECT, TRACE, and TRACK are blocked.
• Headers are a string map and request bodies are strings.
• Redirects are manual. Every visible Location is resolved and checked before the next request, with at most five redirects.
• A missing or WebKit-hidden redirect target is rejected. Cross-origin redirects retain only Accept, Accept-Language, and Content-Type when a body remains. Authorization and cookies are not forwarded.
• The whole chain has a 30-second timeout and a 10 MiB streamed-response limit.

Response headers are restricted to content-type, content-length, etag, last-modified, link, retry-after, x-wp-total, and x-wp-totalpages. set-cookie is never exposed. Text, JSON, XML, JavaScript, and form bodies are decoded in bodyText; non-text responses also include bodyBase64.

Keychain secrets

await api.secrets.set('api-token', token);
const saved = await api.secrets.get('api-token');
if (saved) {
  // Use it through api.net.fetch, then remove it when no longer needed.
  await api.secrets.delete('api-token');
}

The Keychain service is Moldavite. The host constructs the account as plugin:<plugin-id>:<key>, so a worker cannot choose another plugin's namespace. Keys are 1–128 characters, begin with a letter or digit, and then use letters, digits, dots, underscores, or hyphens. Secret values are never listed or included in Forge, settings, plugin, ZIP, or encrypted-backup exports.

Permissions, consent, and failure behavior

Consent is pinned to a SHA-256 hash over the raw manifest.json bytes, a separator, and the plugin.js bytes. Editing source, permissions, or allowedHosts therefore changes the hash and reopens the permission sheet even if version did not change.

Runtime host grants are deliberately separate: they survive a plugin version/hash re-grant, remain visible and individually revocable, and are forgotten with the plugin's consent record when it is uninstalled. They leave files and the content hash unchanged.

Disabling a plugin, uninstalling it, switching Forges, a worker crash, or an unreadable worker message terminates the worker, removes its commands, and rejects pending command invocations. Malformed manifests are marked invalid and never executed.

Worked reference: Publish to WordPress

Moldavite bundles a dependency-free first-party plugin under src-tauri/example-plugin/moldavite-wordpress/. Install it from Settings → Plugins, enable it, and inspect its manifest, source, and README as a complete reference.

1. Configure WordPress publishing uses ui.prompt for an HTTPS site URL, username, and Application Password.
2. It derives the site hostname, calls net.requestHostAccess, and verifies /wp-json/wp/v2/users/me?context=edit before saving configuration through secrets.set.
3. Publish note to WordPress… uses editor.getActiveNote and sends the live editor HTML to /wp-json/wp/v2/posts as a draft.
4. A Keychain-backed Forge-path-to-post-id map makes later publishes of the same path use PUT to update the existing post. The success notification includes the edit URL.

Distribution, updates, and cleanup

• Distribute one folder whose name equals the manifest id and which contains manifest.json, the final self-contained plugin.js, and a README.
• To join the public directory, fork moldavite-plugins, add your folder under plugins/<id>/, update registry.json with the exact SHA-256 hashes and metadata, and open a pull request for review.
• Document every external service, exact manifest host, runtime-host reason, credential key, and destructive or publishing action. Keep requested permissions minimal.
• Registry users install from Browse community plugins. Manual installation by copying the folder to <Forge>/.plugins/ remains available. Enable state and consent are per Forge.
• For an update, replace the plugin files and increment version for human clarity. Any byte change already invalidates the content-hash grant and requires fresh consent.
• Uninstalling in Settings deletes the plugin folder and forgets its consent/runtime-host grant. Keychain secrets remain because plugin secret keys are intentionally hidden from enumeration. Provide a reset command that calls secrets.delete for every known key when users need credential cleanup before uninstalling.
• Test cancellation, missing notes, locked-note rejection, denied/revoked hosts, non-2xx responses, timeouts, malformed JSON, and a plugin disable during an in-flight command.

Older manifests

Existing manifests with "apiVersion": 1 remain valid and receive the original app, commands, editor, and ui.toast surface, with api.app.apiVersion === 1. They do not need a source or manifest migration. Use "apiVersion": 2 for trusted prompts, Forge note reads, networking, and Keychain secrets.