Plugins

Multiforum plugins are versioned packages that run in the backend in response to explicitly configured event pipelines. They can have server settings, channel settings, encrypted secrets, and a generated configuration UI.

Lifecycle

A server administrator:

1. configures one or more plugin registries;
2. allows a plugin from a trusted source;
3. installs an exact version whose artifact passes its SHA-256 integrity check;
4. supplies required secrets and settings;
5. enables that installed version;
6. adds it to an explicit pipeline.

Enabling a plugin makes it selectable. It does not cause the plugin to run on every event. Channel owners can configure channel settings and pipelines only for versions already installed and enabled by the server.

Events

Event	Scope	Description
downloadableFile.created	Server	A downloadable file was uploaded.
downloadableFile.updated	Server	A downloadable file was replaced or modified.
downloadableFile.downloaded	Server	A download request needs a fresh check.
comment.created	Server or channel	A comment was created; a matching channel pipeline takes precedence.
discussionChannel.created	Channel	A discussion was submitted to a channel.

Use Admin → Plugins → Pipelines for server policy and Channel Settings → Pipelines for channel automation. See Plugin pipelines for execution order, rollout policy, permissions, retries, and quarantine.

Plugin manifest

A release contains a plugin.json manifest and its compiled entry point. The minimum useful shape is:

{
  "id": "example-plugin",
  "name": "Example Plugin",
  "version": "1.0.0",
  "description": "What the plugin does.",
  "entry": "dist/index.js",
  "events": ["comment.created"],
  "secrets": [
    {
      "key": "SERVICE_API_KEY",
      "scope": "server",
      "required": true,
      "description": "Credential for the external service."
    }
  ]
}

id, name, version, description, entry, events, and secrets are part of the compatibility contract. Each secret declares a server or forum scope. Optional manifest sections add:

• author, homepage, license, tags, and source/release-note links;
• minimum server and plugin API versions;
• default server and channel settings;
• generated server and channel configuration forms;
• a bundled Markdown README.

The manifest version is the release source of truth. Registry metadata, tarball location, embedded manifest, and release tag must agree.

Secrets and settings

Plugin code receives secrets through its execution context; it must not read deployment environment variables directly. Server secrets are shared for that plugin version across the instance. Forum-scoped secrets belong to one channel configuration.

Secrets are encrypted at rest with PLUGIN_SECRET_ENCRYPTION_KEY. The admin UI shows presence and validation status but never reads the stored plaintext back. Settings are merged from manifest defaults, server overrides, and applicable channel overrides.

When renaming a setting or secret between adjacent releases, declare its renamedFrom source in the new manifest. The backend rejects ambiguous renames, scope changes, and values that do not satisfy the new field schema.

Runtime contract

The package's default export is constructed with a context containing scoped settings, scoped secrets, a logger, and host callbacks. It handles events with handleEvent(event) and returns a structured result whose success controls the job outcome.

Plugins should:

• validate required configuration before doing work;
• return failures instead of leaking thrown provider errors to users;
• use internal logging for request IDs, provider responses, and debugging;
• emit deliberately public diagnostics for information safe to show beside the content;
• use the host flag callback for moderation or scan state when applicable;
• keep heavy or risky file processing in an isolated external service.

See Publishing public pipeline diagnostics for the public contract. Arbitrary logs do not become public diagnostics.

Versioning and upgrades

Administrators can install multiple versions, see registry updates, pin a pipeline step to a version, and roll back. Without a pin, a step resolves the latest enabled compatible version. Each execution records the version and resolved configuration it used, so an upgrade does not rewrite prior history.

Operations as code

The admin UI is appropriate for interactive setup. For reproducible production state, use Declarative plugin configuration to preview and apply versions, settings, secret references, and the complete managed server pipeline list.

The attachment scanner is the reference implementation for delegating untrusted work to an external service. See Security attachment scanning.