MYTOOLBOX · DEVELOPER PLATFORM

Third-party module developer guide

Build Work Mode cards with HTML, CSS, and JavaScript, then connect to MyToolbox through a host-managed Bridge, on-demand authorization, isolated encryption, and seven-day audits.

Current protocolSchema 12 · Compatible with Schema 1–11

12current schema

3runtime surfaces

100 MBpackage limit

512files per package

QUICK START

Start with a card that works offline.

The smallest module is a folder ending in .mytoolbox-workmodule. Its first screen must remain understandable without a network connection, cookies, or granted permissions.

Create the package

Add manifest.json and index.html. settings.json and assets are optional.

Declare a stable identity

Use a permanent reverse-domain identifier, semantic version, bilingual names, an SF Symbol, and a safe relative entry point.

Build an offline first screen

Show meaningful text, controls, images, SVG, or Canvas within four seconds instead of waiting on authorization.

Call the public Bridge

Use window.mytoolbox.request. Permissions are determined by operation; manifest self-declarations do not grant capabilities.

Verify lifecycle behavior

Handle denial, offline mode, stop, reload, and mytoolbox-plugin-stop while cancelling timers and requests.

Import and inspect

Use Plugin Center to verify detected permissions, supported surfaces, audits, encrypted data, and signing identity.

PACKAGE

Minimum package structure

Runtime Cache and Data are created by the host and must not ship in the package. Absolute paths, symbolic links, and .. traversal are rejected.

Example.mytoolbox-workmodule/
├── manifest.json
├── index.html
├── settings.json          # optional native settings
└── assets/                # optional bundled assets

MANIFEST

Schema 12 manifest

The manifest describes identity, surfaces, entry point, size, presentation, commands, and controlled host capabilities. A third-party permissions claim does not authorize access by itself.

{
  "schemaVersion": 12,
  "identifier": "dev.example.weather",
  "version": "1.0.0",
  "runtime": "web",
  "names": {"zh-Hans": "城市天气", "en": "City Weather"},
  "summaries": {"zh-Hans": "当前天气", "en": "Current weather"},
  "symbol": "cloud.sun",
  "entryPoint": "index.html",
  "preferredHeight": 220,
  "supportedSurfaces": ["floatingWindow", "menuBar", "horizontalStrip"],
  "cardSizing": {"mode": "content", "minHeight": 120, "maxHeight": 520},
  "minimumAppVersion": "0.4.0"
}

Identity and entry point

identifier is permanent and must not collide with built-in or installed modules
version uses semantic versioning
runtime is fixed to web for third-party modules
entryPoint must be a safe relative path inside the package
names and summaries should provide both zh-Hans and en

Surfaces and responsive layout

supportedSurfaces accepts floatingWindow, menuBar, and horizontalStrip
horizontalLayout can define a dedicated entry point and width/height boundaries
adaptiveLayout allows constrained host scaling after responsive reflow
cardSizing.content lets the host ResizeObserver measure semantic content

Platform capabilities

presentation supplies an introduction, gallery, contact, and copyright
commandCenter declares up to 24 structured commands
services declares controlled macOS services
dataTransfer manages encrypted portable data
updateActions supports declarative Data/Cache migration only

UI & LIFECYCLE

Plugins own content; the host owns cards and lifecycle.

MyToolbox manages title bars, order, pinning, settings, collapse, close, keyboard focus, and media termination. The real WKWebView does not participate in card-position animation.

Right-side window

Best for vertical information and lightweight tools that stay visible, usually at 330–600pt content width.

Menu-bar popover

Best for short tasks and quick lookups. When not pinned, it closes after an outside click or app focus loss.

Horizontal window

Scrolls horizontally above the Dock and may use a dedicated 260–520pt wide, 160–300pt high entry point.

Stop event

On mytoolbox-plugin-stop, cancel networking, timers, media, and background tasks. Stale results must not refill the UI.

CONTROLLED BRIDGE

One Promise interface, with permission mapped per operation.

For a known operation, the host checks global policy, per-plugin grants, data lock state, and audits at runtime. Dynamic strings or minified source do not bypass enforcement.

const result = await window.mytoolbox.request(
  "currency.snapshot",
  {}
);

OperationPermissionPurpose

clipboard.recent / writeTextclipboardRead / clipboardWrite

Read recent clipboard items or write explicit text

translation.history / executetranslationRead / translationExecute

Read translation history or use the currently selected provider

currency.snapshotcurrencyRead

Read the local MyToolbox exchange-rate snapshot

notes.recentnotesRead

Read recent notes without arbitrary mutation

favorites.recent / asset.read / importfavoritesRead / favoritesWrite

Proxy collection content safely through IDs and Base64

vault.index / entriesvaultMetadataRead / vaultSecretRead

Metadata and secret fields require separate grants

network.fetchnetwork

Use an ephemeral host HTTPS session with no cookies or cache

external.file.readfilePickerRead

Read only a user-selected or persistently authorized file

plugin.window.* / appearance.*nativeWindow / appearance

Ask the host to manage windows or constrained appearance tokens

network.relay.* / packet.*networkRelayControl / packetRelayControl

Use audited relay or temporary packet-stream capabilities

AUTHORIZATION

Render the interface first. Decide capabilities at the call site.

A user can allow once, always allow, or never allow. After never allow, a plugin may link to authorization management but cannot repeatedly show its own prompt.

01Whole-app encryption is enabled and currently unlocked
02Whole-app offline mode does not block the requested network operation
03Trust mode permits the current official, certified, or third-party identity
04The Plugin Center master switch is enabled
05The related global permission ceiling is not disabled
06This plugin holds the individual grant
07Global verification for private permissions is still valid
08A second verification was completed when Vault uses a dedicated key

ENCRYPTED STORAGE

Cache is rebuildable. Data represents important state.

Each plugin uses an independent AES-GCM key derived through HKDF from the app master key and permanent plugin ID. JavaScript never receives file keys or real paths.

await window.mytoolbox.request("plugin.cache.write", {
  path: "Responses/latest.json",
  base64: encoded
});

await window.mytoolbox.request("plugin.data.write", {
  path: "Preferences/state.bin",
  base64: encoded
});

Cache writes are limited to 64 MB and may be safely removed by Mac Optimization
Data writes are limited to 32 MB and are excluded from optimization scans
Paths must remain safe and relative to the plugin directory
Settings, bookmarks, and seven-day audits use the plugin-specific key
Locking MyToolbox removes temporary decrypted directories and stops runtimes

TRUST & SECURITY

A signature proves identity, not unlimited permission.

Official, certified, and ordinary third-party developers have different trust levels, but global enablement, permission ceilings, offline mode, and per-plugin authorization always remain active.

Ed25519 covers the canonical manifest and every release file
Private keys are written only to a user-selected external directory with 0600 permissions
An update with the same identifier cannot change developer or lower signing identity
Failed updates restore the old release; successful updates retain one encrypted snapshot
Certified native companions must be fully signed, App Sandbox enabled, and restricted by command allowlists
The host never exposes Shell, real file paths, bookmarks, passwords, or keys to web or companion processes