---
url: /guide/getting-started.md
---
# Getting started

This page builds a complete, working plugin end-to-end: a **guestbook** with a
private SQLite table, a backend that lists and adds entries, a real-time
broadcast when a new entry lands, and a sidebar panel that renders it. It uses
every layer of the SDK in miniature, so by the end you can read any of the
reference pages and know where each piece fits.

If you only want to surface a self-hosted web app behind a panel (no data, no
logic), skip this and read [Reverse-proxy plugins](/sdk/reverse-proxy) instead.

## 0. Prerequisites

* A running UnCorded server container (launched from the desktop app).
* Access to that server's data directory (`<server-data>/plugins/`) and its
  `server.json`.
* [Bun](https://bun.sh) on your machine for packaging the backend.

## 1. The folder

A plugin is a single folder named exactly its slug. Create:

```
guestbook/
  manifest.json
  backend/
    index.ts
  frontend/
    index.html
  migrations/
    001_init.sql
```

## 2. The manifest

`manifest.json` declares the slug, both entry points, and the **exact**
capabilities the plugin uses. The runtime rejects any IPC call for a capability
not listed here — declare them up front.

```json
{
  "name": "guestbook",
  "version": "0.1.0",
  "api_version": "^1.0",
  "author": "you",
  "description": "A simple server guestbook.",
  "license": "MIT",
  "type": "standalone",
  "icon": "BookOpen",
  "backend": { "entry": "backend/index.ts" },
  "frontend": { "entry": "frontend/index.html" },
  "permissions": ["data.sql:self", "broadcast.clients"],
  "sidebar": { "contributes": true, "section": "Community" }
}
```

* `type: "standalone"` — a third-party plugin that owns its own data. (Core
  plugins shipped by UnCorded use `"core"`; plugins that extend another plugin
  use `"extension"` + `extends`. See the [manifest reference](/reference/manifest).)
* `data.sql:self` — read/write the plugin's own SQLite database.
* `broadcast.clients` — push real-time events to connected clients.

Full field-by-field detail is in the [manifest reference](/reference/manifest);
the capability strings are in the [permissions reference](/reference/permissions).

## 3. The migration

SQL files in `migrations/`, run in filename order at plugin load, build your
schema. Timestamps are stored as Unix-ms integers by convention.

```sql
-- migrations/001_init.sql
CREATE TABLE entries (
  id         TEXT PRIMARY KEY,
  author_id  TEXT NOT NULL,
  message    TEXT NOT NULL,
  created_at INTEGER NOT NULL
);

CREATE INDEX idx_entries_created ON entries(created_at);
```

## 4. The backend

The backend calls `createPlugin()` once, registers its request handlers
**synchronously**, then does any async setup. Handlers receive `(params, user)`
and return any JSON-serializable value; throwing surfaces an error to the caller.

```ts
// backend/index.ts
import { createPlugin } from "@uncorded/plugin-sdk";

interface Entry {
  id: string;
  author_id: string;
  message: string;
  created_at: number;
}

const plugin = createPlugin();

// Read: newest 100 entries.
plugin.handle("listEntries", async () => {
  return plugin.db.query<Entry>(
    "SELECT id, author_id, message, created_at FROM entries ORDER BY created_at DESC LIMIT 100",
  );
});

// Write: validate, insert, broadcast.
plugin.handle("addEntry", async (params, user) => {
  const message = params["message"];
  if (typeof message !== "string" || message.trim().length === 0) {
    throw new Error("message is required");
  }
  if (message.length > 500) {
    throw new Error("message too long");
  }

  const entry: Entry = {
    id: crypto.randomUUID(),
    author_id: user.id,
    message: message.trim(),
    created_at: Date.now(),
  };

  await plugin.db.run(
    "INSERT INTO entries (id, author_id, message, created_at) VALUES (?, ?, ?, ?)",
    [entry.id, entry.author_id, entry.message, entry.created_at],
  );

  // Push to every connected client. The frontend SDK receives this as
  // sdk.on("entry.added", ...) — the runtime namespaces it with the slug.
  await plugin.broadcast.toAll("entry.added", entry);

  return entry;
});

// Tell the shell what to put in the sidebar.
plugin.handle("sidebar.items", async () => ({
  items: [
    {
      id: "guestbook",
      label: "Guestbook",
      icon: "BookOpen",
      panelType: "plugin" as const,
      slug: "guestbook", // must equal manifest "name"
      section: "Community",
    },
  ],
}));
```

`user` is the authenticated caller (`{ id, displayName, avatarUrl, role }`).
Use [`plugin.permissions`](/reference/backend-sdk#permissions) to gate writes by
role when you need to — the guestbook lets any member post.

## 5. The frontend

The panel is plain HTML served into a sandboxed iframe. It loads the frontend
SDK from `/sdk/plugin-frontend.js` (served by the runtime — never bundle it),
initializes, calls backend handlers with `sdk.request(action, params)`, and
listens for broadcasts with `sdk.on(event, handler)`.

```html
<!-- frontend/index.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Guestbook</title>
    <style>
      body { font-family: system-ui, sans-serif; margin: 0; padding: 1rem; }
      #list { list-style: none; padding: 0; }
      #list li { padding: 0.5rem 0; border-bottom: 1px solid #8883; }
      form { display: flex; gap: 0.5rem; margin-top: 1rem; }
      input { flex: 1; }
    </style>
  </head>
  <body>
    <ul id="list"></ul>
    <form id="form">
      <input id="msg" placeholder="Leave a message…" maxlength="500" />
      <button type="submit">Post</button>
    </form>

    <!-- Served by the runtime. Do not bundle it yourself. -->
    <script src="/sdk/plugin-frontend.js"></script>
    <script type="module">
      const sdk = await window.UncodedPlugin.createPluginFrontend();
      const list = document.getElementById("list");

      function prepend(entry) {
        const li = document.createElement("li");
        li.textContent = entry.message;
        list.prepend(li);
      }

      // Initial load.
      const entries = await sdk.request("listEntries");
      for (const e of entries) prepend(e);

      // Live updates pushed by the backend's broadcast.toAll("entry.added", …).
      sdk.on("entry.added", (entry) => prepend(entry));

      // Post a new entry.
      document.getElementById("form").addEventListener("submit", async (ev) => {
        ev.preventDefault();
        const input = document.getElementById("msg");
        if (!input.value.trim()) return;
        await sdk.request("addEntry", { message: input.value });
        input.value = "";
        // No manual insert needed — the broadcast round-trips back to us.
      });
    </script>
  </body>
</html>
```

## 6. Package the backend

The runtime spawns your backend as its own subprocess with the plugin folder as
the working directory. It does **not** run `bun install` for you. Any `import`
(including `@uncorded/plugin-sdk`) must resolve against a `node_modules` present
in the installed folder.

From inside the plugin folder, add a `package.json` and install:

```sh
cd guestbook
bun init -y                       # creates package.json
bun add @uncorded/plugin-sdk      # installs the SDK + deps into node_modules
```

Ship the folder **with `node_modules` present**. (A backend that imports nothing
loads without packaging, but real plugins use the SDK and must be packaged.)

## 7. Install & run

Three things must be true, in order:

1. **Place the folder** under the server's plugin directory, named exactly the
   slug:

   ```
   <server-data>/plugins/guestbook/
   ```

2. **Register the slug** in the server's `server.json` — the runtime only loads
   plugins listed here:

   ```json
   { "installed_plugins": ["guestbook"] }
   ```

3. **Restart through the desktop app** (not `docker restart`). The runtime reads
   `installed_plugins` only at boot, so the container must be recreated. The
   desktop app owns that lifecycle.

   > ⚠️ Never `docker restart` a server on an authenticated Cloudflare tunnel —
   > the tunnel token is piped in at container-create time and a bare restart
   > silently degrades the tunnel. Always go through the desktop app.

Open the server, click **Guestbook** in the sidebar, and post. The message
appears instantly in every open client.

## What you just used

| Layer | This plugin | Reference |
| --- | --- | --- |
| Manifest + capabilities | `data.sql:self`, `broadcast.clients` | [Manifest](/reference/manifest) · [Permissions](/reference/permissions) |
| Own database | `plugin.db.query` / `plugin.db.run` | [Backend SDK → db](/reference/backend-sdk#db) |
| Request handlers | `plugin.handle("addEntry", …)` | [Backend SDK → handle](/reference/backend-sdk#handle-request) |
| Real-time push | `plugin.broadcast.toAll` → `sdk.on` | [Backend SDK → broadcast](/reference/backend-sdk#broadcast) |
| Panel UI | `createPluginFrontend()`, `sdk.request` | [Frontend SDK](/reference/frontend-sdk) |

Next: [Plugin anatomy](/guide/plugin-anatomy) breaks down every file and how the
runtime treats it.

---

---
url: /guide/plugin-anatomy.md
---
# Plugin anatomy

A plugin is one folder, named exactly its slug, containing a manifest and one or
both entry points. This page is the map: what each file is, how the runtime
treats it, and the packaging rule that trips up most first attempts.

## The folder

```
my-plugin/
  manifest.json          ← required. Slug, entry points, capabilities, settings.
  backend/
    index.ts             ← backend entry (path is set by manifest.backend.entry)
  frontend/
    index.html           ← frontend entry (path is set by manifest.frontend.entry)
  migrations/
    001_init.sql         ← SQL run in filename order at load (data-owning plugins)
    002_add_column.sql
  node_modules/          ← REQUIRED if the backend imports anything (see Packaging)
  package.json           ← how you install node_modules
```

Only `manifest.json` plus at least one entry point is mandatory. A frontend-only
plugin omits `backend`; a headless plugin omits `frontend`; a reverse-proxy
plugin needs both but the backend is a few lines.

The folder name **must** equal the manifest `name`. That slug is the plugin's
identity everywhere: the install directory, the `installed_plugins` entry, the
DB filename, broadcast namespacing, and proxy/upload URLs.

## manifest.json

The contract between your plugin and the runtime. It is validated at load; an
invalid manifest means the plugin is skipped. The fields you'll touch most:

| Field | Purpose |
| --- | --- |
| `name` | Slug. `^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`. |
| `version` / `api_version` | Plugin semver / runtime-API semver range (`^1.0`). |
| `type` | `core` | `standalone` | `extension`. Third-party = `standalone`. |
| `backend` / `frontend` | `{ "entry": "<path>" }`. At least one required. |
| `permissions` | The capabilities the runtime will allow. Undeclared = rejected. |
| `settings` | Admin-configurable values, rendered as a form in Server settings. |
| `sidebar` | `{ "contributes": true, … }` to put items in the client sidebar. |
| `public_schema` | Tables/columns you expose for cross-plugin reads. |

Full reference: [Manifest](/reference/manifest). Capability grammar:
[Permissions](/reference/permissions).

## backend/

The backend is a Bun program the runtime spawns as a **subprocess**. It speaks
the stdio JSON [IPC protocol](/reference/ipc-protocol), but you never touch that
directly — `createPlugin()` from `@uncorded/plugin-sdk` wraps it into a typed
handle.

Structure every backend the same way:

```ts
import { createPlugin } from "@uncorded/plugin-sdk";

const plugin = createPlugin();

// 1. Register handlers SYNCHRONOUSLY, at module top level, so they exist before
//    the runtime starts routing requests.
plugin.handle("doThing", async (params, user) => { /* … */ });
plugin.handle("sidebar.items", async (_params, user) => ({ items: [/* … */] }));

// 2. THEN do async setup: register permissions, subscribe to events, register
//    schedules, warm caches.
await plugin.permissions.register("my-plugin.post", { description: "…", default_level: 10 });
await plugin.events.subscribe("runtime.cascade.user.deleted", async (e) => { /* … */ });
```

Why the order matters: handler registration is local and instant; async setup
involves IPC round-trips. Registering handlers first guarantees a request that
arrives mid-startup has somewhere to land. See the
[text-channels walkthrough](/examples/text-channels) for a full backend.

The `createPlugin()` handle exposes the whole backend surface — `db`, `kv`,
`settings`, `events`, `broadcast`, `presence`, `schedule`, `fetch`, `core`,
`data`, `permissions`, `resources`, `files`, `voice`. Reference:
[Backend SDK](/reference/backend-sdk).

### Two reserved handler actions

| Action | Called by | Returns |
| --- | --- | --- |
| `sidebar.items` | the shell, to build the sidebar | `{ items: SidebarItem[], adminActions?: [] }` |
| `schedule.tick` | the runtime, on a registered schedule | (handled for you by `plugin.schedule.every`) |

Everything else is an action name you choose and the frontend calls by string.

## frontend/

The frontend entry (an HTML file) is served into a **sandboxed iframe** inside
the client shell. It has no same-origin access to the shell; all communication
goes through an origin-verified `postMessage` channel that the frontend SDK
manages for you.

```html
<script src="/sdk/plugin-frontend.js"></script>
<script type="module">
  const sdk = await window.UncodedPlugin.createPluginFrontend();
  // sdk.request(...), sdk.on(...), sdk.subscribe(...), sdk.files, sdk.proxy,
  // sdk.platform.* — see the Frontend SDK reference.
</script>
```

* Load `/sdk/plugin-frontend.js` from the runtime. **Do not** bundle or vendor
  it — it's served and cache-busted by the runtime so it stays in lockstep.
* The HTML is served as-is. **No build step** — inline your CSS and JS, or ship
  pre-built assets alongside `index.html`.
* `createPluginFrontend()` resolves after the handshake completes; everything
  else hangs off the returned `sdk`.

Reference: [Frontend SDK](/reference/frontend-sdk).

## migrations/

Data-owning plugins (those with `data.sql:self`) get a private SQLite database.
SQL files in `migrations/` run **in filename order** at plugin load to build and
evolve the schema:

* `001_init.sql` — `CREATE TABLE` + any seed rows.
* `002_*.sql`, `003_*.sql` — `ALTER TABLE`, new tables, backfills.

Conventions from the core plugins: integer Unix-ms timestamps
(`strftime('%s','now') * 1000` for seeds), explicit column lists in `SELECT`
(don't `SELECT *` — it leaks columns added by a later migration before your wire
contract catches up), and soft foreign keys checked in code rather than
`REFERENCES` constraints across plugin boundaries.

More on the database, KV, and events: [Data & events](/guide/data-and-events).

## Packaging — backends run as subprocesses

The single most common reason a plugin won't load. The runtime executes your
backend as its own subprocess with the plugin folder as the working directory:

```
Bun.spawn(["bun", "--smol", "run", "<backend entry>"], { cwd: "<plugin folder>" })
```

The runtime **does not** install your dependencies. So:

* Any `import` resolves against the plugin folder's **own `node_modules`**.
* **Ship `node_modules` in the installed folder** — either commit it, or include
  a `package.json` + lockfile and run `bun install` in the folder before
  installing the plugin.

```sh
cd my-plugin
bun add @uncorded/plugin-sdk   # populates node_modules/
```

> A backend that imports nothing (raw stdio) loads without packaging, but any
> real plugin imports the SDK and therefore must be packaged with its deps.

## Where data lives on disk

Inside the container, each plugin gets an isolated directory (mode `0700`):

```
/data/plugins/<slug>/
  <slug>.db            ← the plugin's private SQLite (WAL mode)
  <slug>.db-wal
  <slug>.db-shm
  uploads/             ← files POSTed to /upload, served via signed URLs
```

A plugin can never open another plugin's database for writing. Cross-plugin
reads go through the [`data.read`](/reference/backend-sdk#data) capability, which
opens the target DB read-only and enforces the target's `public_schema`.

Next: [Lifecycle](/guide/lifecycle) — exactly what happens from spawn to
shutdown, including the readiness handshakes and the watchdog.

---

---
url: /guide/lifecycle.md
---
# Lifecycle

What the runtime does to your plugin, from boot to shutdown. Understanding this
explains why handlers must register synchronously, when `serveReady()` matters,
and why a crash loop quarantines a plugin.

## 1. Discovery

At boot the runtime reads `server.json` → `installed_plugins: string[]`. For each
slug it resolves a folder (core plugins first, then user plugins) and reads
`manifest.json`. A slug with no resolvable manifest is **skipped with a warning**
— it doesn't block boot. A plugin marked disabled in settings is also skipped.

> The list is read **only at boot**. Adding a slug to `installed_plugins`
> requires recreating the container (restart via the desktop app), not a hot
> reload.

## 2. Database & migrations

Before spawning, the runtime prepares the plugin's data directory
(`/data/plugins/<slug>/`, mode `0700`) and runs the SQL files in `migrations/`
in filename order. The SQLite database opens in WAL mode on first use. If a
migration throws, the plugin is skipped with an error.

## 3. Spawn

The backend is launched as its own subprocess:

```
Bun.spawn(["bun", "--smol", "run", "<backend entry>"], {
  cwd: "<plugin folder>",
  stdin: "pipe", stdout: "pipe", stderr: "pipe",
  env: {
    PLUGIN_SLUG, PLUGIN_API_VERSION, PLUGIN_DATA_DIR,
    NODE_OPTIONS: "--max-old-space-size=256",  // memory guard (cgroup is authoritative)
  },
})
```

* `--smol` runs Bun in low-memory mode (more frequent GC).
* `stdin`/`stdout` are owned by the IPC transport — **don't read stdin** or write
  raw protocol to stdout. Unprefixed stdout and all stderr are captured as logs.
* The plugin folder is the working directory, which is why imports resolve
  against the folder's own `node_modules` ([packaging](/guide/plugin-anatomy#packaging-backends-run-as-subprocesses)).

## 4. The ready handshake {#the-ready-handshake}

`createPlugin()` sends `{ "type": "ready" }` to the runtime as the last thing it
does. The runtime waits up to **30 seconds** for it; no ready frame in that
window is a `HANDSHAKE_TIMEOUT` and the spawn fails.

`ready` only proves the **process is alive and the SDK is wired** — not that your
caches are warm. For most plugins that's enough and the runtime starts routing
requests immediately.

## 5. The optional serve-ready handshake {#the-optional-serve-ready-handshake}

If your plugin needs to hydrate state before it can answer requests (warm a
cache, prefetch from an external service), opt into the two-stage handshake:

```json
{ "serve_ready_handshake": true }
```

With it set, the runtime registers the plugin as **not-ready-to-serve**: the
client greys out the plugin's sidebar items until you signal completion:

```ts
// after caches are loaded, member lists fetched, etc.
plugin.serveReady();
```

Without the opt-in, `serveReady()` is a harmless no-op (the plugin is treated as
serve-ready the moment it spawns). Use it to avoid surfacing clickable rows the
plugin can't yet answer — otherwise a freshly provisioned server can show a
channel that silently fails to open.

## 6. Watchdog (ping / pong)

Every **10 seconds** the runtime sends `{ "type": "ping" }` to each ready
plugin. The SDK auto-responds with `{ "type": "pong" }` — you write no code for
this. Miss **3 consecutive pings (30s)** and the runtime force-kills the
subprocess as hung.

A plugin that blocks the event loop (a long synchronous loop) can miss pongs and
get killed. Keep handlers async and yield; offload heavy work or chunk it.

## 7. Crash, restart & quarantine

When a subprocess exits unexpectedly, the runtime restarts it on a backoff
schedule: **1s → 2s → 5s → 15s → 60s**. If a plugin crashes **5 times within 10
minutes** it is **quarantined** — no further restarts until manual intervention.
This stops a broken plugin from pinning CPU in a tight crash loop.

A graceful stop (below) or a clean exit does not count toward the crash budget.

## 8. Shutdown

On unload (server stop, plugin disable, container teardown) the runtime stops the
plugin gracefully:

1. Send `SIGTERM`, wait up to **5 seconds** for a clean exit.
2. `SIGKILL` if it hasn't exited.
3. Close the transport and fire unload callbacks (managed services released, etc.).

To shut down cleanly, let your event loop drain — flush pending writes in handler
paths, not in an exit hook, since `SIGKILL` after the grace window won't run one.

## Reference: the message frames

You won't send these directly (the SDK does), but they're useful when reading
logs or debugging:

| Frame | Direction | Meaning |
| --- | --- | --- |
| `ready` | plugin → runtime | SDK initialized; begin routing. |
| `serve_ready` | plugin → runtime | Caches warm; un-grey sidebar items. |
| `ping` / `pong` | runtime ⇄ plugin | Watchdog heartbeat (auto-handled). |
| `request` / `response` | runtime ⇄ plugin | A handler invocation and its result. |
| `event.deliver` / `event.ack` | runtime ⇄ plugin | Event bus delivery + acknowledgement. |

Full protocol: [IPC protocol](/reference/ipc-protocol).

---

---
url: /guide/data-and-events.md
---
# Data & events

How a plugin stores state, reacts to things happening, and pushes updates to
clients. Four mechanisms, each with a different shape:

| Mechanism | For | Capability |
| --- | --- | --- |
| **SQLite** (`plugin.db`) | structured, queryable, durable data | `data.sql:self` |
| **KV** (`plugin.kv`) | simple string key/value | `data.kv:self` |
| **Event bus** (`plugin.events`) | plugin ↔ plugin / runtime, durable, acked | `events.publish` / `events.subscribe` |
| **Broadcast** (`plugin.broadcast`) | backend → connected clients, fire-and-forget | `broadcast.clients` |

## SQLite — your own database

Each data-owning plugin gets a private SQLite database (WAL mode). All access is
routed through IPC, so every call is `async`:

```ts
// SELECT → array of row objects
const rows = await plugin.db.query<Channel>(
  "SELECT id, name FROM channels WHERE category_id = ? ORDER BY position",
  [categoryId],
);

// INSERT/UPDATE/DELETE → { changes, lastInsertRowid }
const res = await plugin.db.run(
  "UPDATE channels SET name = ? WHERE id = ?",
  [name, id],
);

// DDL / PRAGMA → void
await plugin.db.exec("CREATE TABLE IF NOT EXISTS …");

// Multiple statements, atomically
await plugin.db.batch([
  { sql: "INSERT INTO messages (...) VALUES (...)", params: [...] },
  { sql: "UPDATE messages SET reply_count = reply_count + 1 WHERE id = ?", params: [parentId] },
]);
```

Always use **parameter placeholders** (`?`), never string interpolation. Use
`batch()` when several writes must land together. Schema is built by
[migrations](/guide/plugin-anatomy#migrations). Full method list:
[Backend SDK → db](/reference/backend-sdk#db).

### Cross-plugin reads

To read another plugin's data, that plugin must publish the table in its
manifest `public_schema`, and you must declare `data.read:<plugin>.<table>`. You
then get a read-only query builder:

```ts
const channels = await plugin.data
  .read("text-channels", "channels")
  .where("category_id", "=", categoryId)
  .select(["id", "name"])
  .orderBy("position")
  .limit(50)
  .exec();
```

Only published columns are readable; the target DB is opened read-only. There is
no cross-plugin write — ever.

## KV — string key/value

Backed by a `_kv` table in your own SQLite. Values are **always strings** —
serialize objects yourself. Requires `data.kv:self`.

```ts
await plugin.kv.set("config:theme", JSON.stringify({ accent: "blue" }));
const raw = await plugin.kv.get("config:theme");        // string | null
const all = await plugin.kv.list("config:");            // prefix scan
const many = await plugin.kv.getMany(["a", "b", "c"]);  // one round-trip
await plugin.kv.delete("config:theme");
```

Reach for KV for small, flat state (a counter, a cached token, a feature flag).
For anything you'd query or filter, use SQLite.

## Settings — admin-configurable values

Settings declared in the manifest's `settings` array are editable by admins in
Server settings and readable by your plugin. No capability needed — a plugin
always reads its own settings.

```ts
const len = await plugin.settings.get("max_message_length");  // value or manifest default
const all = await plugin.settings.getAll();

// React to an admin changing a value while the plugin runs:
plugin.settings.onChange((ev) => {
  console.error(`setting ${ev.key} → ${ev.value}`); // refresh your cache
});
```

The common pattern (from text-channels): cache settings at module scope, refresh
on boot, and re-read in `onChange`. See the
[example walkthrough](/examples/text-channels#settings).

## Event bus — durable, acked, plugin-to-plugin

The event bus is for **state changes other plugins (or the runtime) care about**.
Delivery is **at-least-once** with **per-(topic, subscriber) FIFO** ordering;
each delivery is acknowledged by the SDK automatically.

```ts
// Publish. Topic must be in your own namespace (your slug). Requires
// events.publish:<slug>.* (or a specific topic).
plugin.events.publish("text-channels.channel.created", channel);

// Subscribe. Requires events.subscribe:<pattern>. Returns once the
// subscription is acknowledged.
await plugin.events.subscribe("core.category.deleted", async (event) => {
  const id = (event.payload as { id: string }).id;
  await plugin.db.run("UPDATE channels SET category_id = NULL WHERE category_id = ?", [id]);
});
```

Key rules:

* You publish only into your **own** namespace; the `runtime.*` namespace is
  reserved for the runtime.
* Subscribe with a prefix wildcard (`text-channels.*`) or an exact topic. A bare
  `*` is not allowed for subscribe.
* **Backpressure** (`SubscribeOptions.overflow_policy`): the default is
  `mark_unhealthy` — if your subscriber's queue fills, the subscription is marked
  unhealthy (failures are loud, not silently dropped). `drop_oldest` /
  `drop_newest` opt into lossy delivery instead.

### Runtime-published events you can subscribe to

The runtime emits lifecycle events plugins commonly react to. These fire today:

| Topic | Fires when | Typical use |
| --- | --- | --- |
| `runtime.cascade.user.banned` | Central reports a user banned (payload `{ user_id, reason }`) | revoke their access, close sessions |
| `runtime.cascade.user.profile_changed` | a user's username/display name/avatar changes | refresh cached author profiles |
| `runtime.presence.joined` / `.updated` / `.left` | a user connects/disconnects or scoped presence changes (also via `plugin.presence`) | live member state |
| `core.category.created` / `.updated` / `.deleted` / `.reordered` | an admin manages sidebar categories (`.deleted` payload `{ id }`) | null soft-FKs, re-render groups |

Subscribe to a family with a wildcard — `runtime.cascade.*`, `runtime.presence.*`,
`core.category.*` — and switch on the exact topic inside the handler. Subscribing
requires the matching `events.subscribe:` capability.

::: warning Reserved, not yet emitted
`runtime.cascade.user.deleted` (account deletion) is a **reserved** topic: it is
part of the contract and safe to subscribe to, but the runtime does not emit it
yet — the delta handler is wired up once Central adds account-deletion to its
heartbeat delta protocol. A subscription compiles and registers fine; the handler
simply never fires until then. Don't rely on it as your only cleanup path for
removed users today. (`core.user.deleted` is defined alongside it and is gated on
the same Central work.)
:::

## Broadcast — push to connected clients

Broadcast is the **backend → client** channel for real-time UI updates. It's
fire-and-forget (no ack, not durable) and lands in the frontend SDK as
`sdk.on(event, …)`. Requires `broadcast.clients`.

```ts
await plugin.broadcast.toUser(userId, "notification", { text: "…" });
await plugin.broadcast.toUsers([u1, u2], "typing.updated", { users });  // ≤ 100 ids
await plugin.broadcast.toAll("entry.added", entry);
```

The runtime namespaces the event with your slug on the wire
(`"entry.added"` → `"guestbook.entry.added"`); the frontend SDK strips the prefix
so you write `sdk.on("entry.added", …)`. See
[Frontend SDK → on](/reference/frontend-sdk#on-broadcasts).

### Event bus vs. broadcast — which one?

* **Other plugins or durability matter** → event bus (`plugin.events`).
* **Just update open client UIs right now** → broadcast (`plugin.broadcast`).

A common pairing: write to SQLite, `events.publish` for any plugin that's
listening, and `broadcast.toAll` so open panels update instantly.

## Presence

`plugin.presence` gives you connect/disconnect hooks (no capability) and scoped,
ephemeral presence (who's "in" a channel, who's typing) folded under
`broadcast.clients`:

```ts
plugin.presence.onConnected((user) => { /* … */ });

// Inside a request handler (it infers the WS session from request context):
const leave = await plugin.presence.join(`channel.${id}.typing`, user.id, {
  typing_until: Date.now() + 4000,
});
const unwatch = await plugin.presence.watch(`channel.${id}.typing`, (entries) => {
  // broadcast the live list to viewers
}, { coalesceMs: 50 });
```

Scopes are auto-prefixed with your slug. `join`/`leave`/`update` must run inside
a request handler's async context (they throw `PRESENCE_NO_SESSION_CONTEXT`
otherwise). Full surface: [Backend SDK → presence](/reference/backend-sdk#presence).

---

---
url: /reference/manifest.md
---
# Manifest reference

`manifest.json` is the contract between a plugin and the runtime. It is validated
at load against [`packages/shared/src/manifest.ts`](https://github.com/UnCorded/uncorded-platform/blob/main/packages/shared/src/manifest.ts);
an invalid manifest means the plugin is skipped. Unknown top-level fields are
**rejected** (typo protection), so the table below is the complete allowed set.

## Minimal example

```json
{
  "name": "guestbook",
  "version": "0.1.0",
  "api_version": "^1.0",
  "author": "you",
  "description": "A simple server guestbook.",
  "type": "standalone",
  "backend": { "entry": "backend/index.ts" },
  "frontend": { "entry": "frontend/index.html" },
  "permissions": ["data.sql:self", "broadcast.clients"]
}
```

## Top-level fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `name` | string | ✅ | Slug. Must match `^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$` — lowercase, starts with a letter, no leading/trailing/consecutive hyphens. This is the plugin's identity everywhere. |
| `version` | string | ✅ | Strict semver `MAJOR.MINOR.PATCH`. No pre-release/build metadata. |
| `api_version` | string | ✅ | Runtime-API compatibility range, e.g. `^1.0`. |
| `author` | string | ✅ | Non-empty. |
| `description` | string | ✅ | Non-empty. |
| `type` | `"core"` | `"standalone"` | `"extension"` | ✅ | See [Plugin type](#plugin-type-extends). |
| `permissions` | string\[] | ✅ | Capability strings the runtime will allow. May be empty for a frontend-only plugin. See [Permissions](/reference/permissions). |
| `extends` | string | conditional | **Required** iff `type: "extension"`; forbidden otherwise. The base plugin's slug. |
| `backend` | `{ entry: string }` | conditional | Backend entry path. At least one of `backend`/`frontend` required. |
| `frontend` | `{ entry: string }` | conditional | Frontend entry path (HTML). |
| `license` | string | optional | e.g. `"MIT"`. |
| `icon` | string | optional | lucide-icon name (e.g. `"Hash"`). Max 64 chars. Unknown names render a placeholder. |
| `settings` | `PluginSetting[]` | optional | Admin-configurable settings. See [Settings](#settings). |
| `sidebar` | object | optional | Sidebar contribution. See [Sidebar](#sidebar). |
| `public_schema` | `Record<string, { columns, description }>` | optional | Tables/columns exposed for cross-plugin reads. See [public\_schema](#public_schema). |
| `dependencies` | `Record<slug, semverRange>` | optional | Other plugins this one depends on. |
| `resources` | `{ memory_mb?, cpu_weight?, disk_mb? }` | optional | Resource hints. Positive integers. |
| `proxy_mounts` | `ProxyMount[]` | optional | Reverse-proxy mounts. See [proxy\_mounts](#proxy_mounts) and the [reverse-proxy guide](/sdk/reverse-proxy). |
| `serve_ready_handshake` | boolean | optional | Opt into the two-stage readiness handshake. See [Lifecycle](/guide/lifecycle#the-optional-serve-ready-handshake). Default `false`. |
| `client_capabilities` | string\[] | optional | Client platform requirements. V1: only `"client.browser"`. |
| `runtime_capabilities` | string\[] | optional | Runtime opt-ins: `"voice.media"`, `"voice.screen_share"`, `"voice.moderation"`. Unknown values rejected. |
| `managed_services` | string\[] | optional | Sidecar services the runtime supervises. Recognized: `"livekit"`. |

## Plugin type & `extends`

| `type` | Meaning | `extends` |
| --- | --- | --- |
| `core` | Shipped by UnCorded (text-channels, voice-channels, members, moderation). | forbidden |
| `standalone` | Third-party plugin with its own functionality and data. | forbidden |
| `extension` | Third-party plugin that extends a base plugin. | **required** — the base plugin slug |

Most third-party plugins are `standalone`.

## Settings

Each entry in `settings[]` is rendered as a form field in Server settings and is
readable via [`plugin.settings`](/reference/backend-sdk#settings).

```json
{
  "key": "max_message_length",
  "label": "Max message length",
  "description": "Maximum characters allowed per message.",
  "type": "number",
  "default": 5000,
  "stops": [
    { "value": 2000, "label": "2k" },
    { "value": 5000, "label": "5k" },
    { "value": 0,    "label": "Unlimited" }
  ]
}
```

| Field | Type | Applies to | Notes |
| --- | --- | --- | --- |
| `key` | string | all | Unique within the plugin. Max 256 chars. |
| `label` | string | all | Shown in the admin panel. |
| `description` | string | all | Optional help text. |
| `type` | `"string"` | `"secret"` | `"number"` | `"boolean"` | — | `secret` values are redacted from logs and masked in the UI. |
| `required` | boolean | all | Surfaced as a warning if unset. |
| `default` | string | number | boolean | all | Must match `type`. Used when unset. |
| `min` / `max` / `step` | number | `number` | Bounds and slider step (`step > 0`). |
| `stops` | `{ value, label }[]` | `number` | Stepped slider with labelled positions. Stored value is the underlying number (e.g. `0` = "unlimited"). |
| `max_length` | number | `string`/`secret` | Server-enforced length cap (positive). |
| `enum` | string\[] | `string` | Renders a select; `default` must be a member. |

Cross-field validation enforces `min ≤ default ≤ max`, `default` length ≤
`max_length`, `default` ∈ `enum`, and `default` matching a `stops` value.

## Sidebar

```json
{ "sidebar": { "contributes": true, "section": "Chat", "refresh_on": ["text-channels.channel.created"] } }
```

| Field | Type | Notes |
| --- | --- | --- |
| `contributes` | boolean | Required. `true` if the plugin returns sidebar items. |
| `section` | string | Optional default group name for this plugin's items, used when an item doesn't set its own `section`. |
| `refresh_on` | string\[] | Event topics that trigger a re-fetch of the plugin's sidebar items. |

The items themselves come from the backend's `sidebar.items` handler, not the
manifest. See [Plugin anatomy → reserved actions](/guide/plugin-anatomy#two-reserved-handler-actions).

## public\_schema

Declares which of your tables and columns are readable by other plugins (via
their [`data.read`](/reference/backend-sdk#data) capability):

```json
{
  "public_schema": {
    "messages": {
      "columns": ["id", "channel_id", "author_id", "content", "created_at"],
      "description": "All messages across all channels."
    }
  }
}
```

Only listed columns are readable; everything else stays private.

## proxy\_mounts

```json
{
  "proxy_mounts": [
    { "name": "demo", "upstream_setting": "demo_upstream_url", "access": "members" }
  ]
}
```

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string | Slug-safe, unique within the plugin. Appears in the URL `/proxy/<slug>/<name>/*`. |
| `upstream_setting` | string | Key of a `string`/`secret` setting **in this same manifest** holding the upstream URL. The manifest never carries the URL directly. |
| `access` | `"members"` | `"owner"` | Optional, default `"members"`. |
| `max_frame_bytes` | integer | Optional. Max **WebSocket** frame (message) size relayed in either direction, in bytes. A larger frame closes the socket with `1009`. Default **65536** (64 KiB); raise it for apps that bulk-sync over a socket (e.g. game state). Must be between **1024** (1 KiB) and **16777216** (16 MiB). |

Declaring `proxy_mounts` requires at least one of `proxy.http:self` /
`proxy.websocket:self` in `permissions`. Mounts are disabled until an owner
approves them. Full guide: [Reverse-proxy plugins](/sdk/reverse-proxy).

## Validation rules (summary)

* At least one of `backend` / `frontend`.
* `type: "extension"` ⇒ `extends` present and a valid slug; `core`/`standalone`
  ⇒ no `extends`.
* Every `permissions` entry matches the [capability grammar](/reference/permissions#grammar).
* `proxy_mounts[].upstream_setting` references a declared `string`/`secret`
  setting; mount names unique; proxy permission present.
* `proxy_mounts[].max_frame_bytes`, when present, is an integer in
  `[1024, 16777216]`.
* Settings `default` consistent with `type`/`min`/`max`/`max_length`/`enum`/`stops`.
* `resources.*` positive integers; `icon` ≤ 64 chars; unknown top-level or
  per-setting fields rejected.

The tests in [`packages/shared/src/manifest.test.ts`](https://github.com/UnCorded/uncorded-platform/blob/main/packages/shared/src/manifest.test.ts)
are the exhaustive, executable spec.

---

---
url: /reference/permissions.md
---
# Permissions reference

Every IPC call a plugin makes is checked against the capabilities listed in its
manifest `permissions` array. **Undeclared = hard reject** — there is no implicit
trust and no runtime workaround. Getting this array right is where most
first-attempt plugins fail, so this page maps each SDK feature to the exact
string it needs.

Two distinct concepts share the word "permission":

1. **Capabilities** (this page) — manifest strings that gate the plugin's access
   to runtime services. Enforced by the runtime on every IPC call.
2. **User permissions** — role/permission checks *your plugin* runs on its
   *users* via [`plugin.permissions`](/reference/backend-sdk#permissions) (e.g.
   "can this user post?"). Registered with `plugin.permissions.register()`. These
   are application logic, not manifest declarations.

## Grammar

```
resource.action[:scope]
```

Validated against:

```js
/^[a-z][a-zA-Z0-9]*\.[a-zA-Z][a-zA-Z0-9]*(?::[a-z0-9*][a-z0-9.*:-]*)?$/
```

`resource` and `action` are dotted identifiers; `scope` is optional and may
contain dots, colons, and `*` wildcards. Scope conventions:

* `:self` — the plugin's own resource (its own DB, its own files).
* `:<plugin>.<table>` — a specific cross-plugin target.
* `:<namespace>.*` — a prefix wildcard (events).
* `:<hostname>[:port]` — a network target (fetch).

## Capabilities by feature

| Capability | Unlocks (SDK) | Scope rules |
| --- | --- | --- |
| `data.sql:self` | [`plugin.db`](/reference/backend-sdk#db) — own SQLite | `:self` only |
| `data.kv:self` | [`plugin.kv`](/reference/backend-sdk#kv) — own key/value store | `:self` only |
| `data.read:<plugin>.<table>` | [`plugin.data.read`](/reference/backend-sdk#data) — read another plugin's published table | **no wildcards** — name an exact `plugin.table` |
| `events.publish:<ns>.*` | [`plugin.events.publish`](/reference/backend-sdk#events) | prefix wildcard or exact topic; publish only to **your** namespace |
| `events.subscribe:<pattern>` | [`plugin.events.subscribe`](/reference/backend-sdk#events) | prefix wildcard (`x.*`) or exact topic; **bare `*` rejected** |
| `broadcast.clients` | [`plugin.broadcast`](/reference/backend-sdk#broadcast) + scoped [`plugin.presence`](/reference/backend-sdk#presence) | no scope |
| `storage.file:self` | [`plugin.files`](/reference/backend-sdk#files) + the `/upload` endpoint | `:self` only |
| `http.fetch:<host>[:port]` | [`plugin.fetch`](/reference/backend-sdk#fetch) — outbound HTTP to that host | exact hostname (+ optional port) |
| `runtime.schedule` | [`plugin.schedule`](/reference/backend-sdk#schedule) — recurring tasks | no scope |
| `runtime.log` | structured logging to the runtime collector | no scope |
| `auth.currentUser` | current-user lookups | no scope |
| `voice.tokens:self` | [`plugin.voice.createJoinToken`](/reference/backend-sdk#voice) | `:self` |
| `voice.moderation:self` | [`plugin.voice.removeParticipant`](/reference/backend-sdk#voice) | `:self` |
| `proxy.http:self` | reverse-proxy HTTP forwarding for a `proxy_mount` | `:self` |
| `proxy.websocket:self` | reverse-proxy WebSocket forwarding (not implied by HTTP) | `:self` |
| `resources.read:<plugin>` | cross-plugin [`plugin.resources.check`](/reference/backend-sdk#resources) | exact owner-plugin slug |

> Capabilities that need **no** declaration: reading your own
> [`settings`](/reference/backend-sdk#settings), the [`core`](/reference/backend-sdk#core)
> user/category cache, presence connect/disconnect hooks, and registering your
> own [user permissions](/reference/backend-sdk#permissions). These are always
> available.

## runtime\_capabilities (separate array)

Voice features are opted into via the manifest's `runtime_capabilities` array,
**not** `permissions`:

| Value | Gates |
| --- | --- |
| `voice.media` | LiveKit-mediated audio (the voice-channels plugin). |
| `voice.screen_share` | the plugin's ability to grant screen-share publish. |
| `voice.moderation` | admin "Stop their share" via LiveKit `RemoveParticipant`. |

Per-user authorization (e.g. `voice.screen_share.publish`) is a separate *user
permission* your plugin registers and checks — see above.

## Wildcard rules at a glance

| Pattern | `data.read` | `events.publish` | `events.subscribe` |
| --- | --- | --- | --- |
| exact (`x.y`) | ✅ | ✅ | ✅ |
| prefix (`x.*`) | ❌ | ✅ | ✅ |
| bare `*` | ❌ | ✅ | ❌ |

## Worked example

The text-channels plugin declares:

```json
"permissions": [
  "data.sql:self",
  "events.publish:text-channels.*",
  "events.subscribe:runtime.cascade.*",
  "events.subscribe:runtime.presence.*",
  "events.subscribe:text-channels.*",
  "events.subscribe:core.category.*",
  "broadcast.clients",
  "storage.file:self",
  "runtime.schedule"
]
```

Reading top to bottom: it owns a database, publishes its own events, listens for
user-deletion cascades, presence, its own events, and category deletions, pushes
real-time updates to clients, stores uploaded files, and runs a scheduled
orphan-GC sweep. Every SDK call it makes traces back to one of these lines.

The capability checker and its test suite are the executable spec:
[`runtime/src/capabilities/checker.ts`](https://github.com/UnCorded/uncorded-platform/blob/main/runtime/src/capabilities/checker.ts).

---

---
url: /reference/backend-sdk.md
---
# Backend SDK reference

`@uncorded/plugin-sdk`. Call `createPlugin()` once at startup; it wires the stdio
IPC transport, sends the `ready` handshake, and returns a `PluginHandle` exposing
the entire backend surface. Source of truth:
[`packages/plugin-sdk/src/types.ts`](https://github.com/UnCorded/uncorded-platform/blob/main/packages/plugin-sdk/src/types.ts).

```ts
import { createPlugin } from "@uncorded/plugin-sdk";

const plugin = createPlugin(/* { onFileUploaded } */);
```

`createPlugin(options?)` accepts one option, `onFileUploaded`, a callback fired
when a client finishes uploading a file to this plugin (see [files](#files)).

All methods that cross to the runtime are `async`. Errors arrive as
[`SdkError` / `SdkProtocolError`](#errors) with a stable `.code`.

## handle / request

```ts
plugin.handle(action: string, handler: (params, user) => unknown | Promise<unknown>): void
plugin.request<T>(action: string, params?: Record<string, unknown>): Promise<T>
```

* **`handle`** registers a handler for an inbound action. `params` is the
  caller's arguments; `user` is the authenticated caller
  (`{ id, displayName, avatarUrl, role }`). Return any JSON-serializable value;
  throwing surfaces an error to the caller. Register handlers **synchronously at
  startup** so they exist before the runtime routes requests.
* **`request`** sends a request to the runtime (cross-plugin calls / runtime
  services).

Two action names are special: `sidebar.items` (the shell calls it to build the
sidebar) and `schedule.tick` (handled for you by [`schedule`](#schedule)).

```ts
plugin.handle("getMessages", async (params, user) => {
  const channelId = params["channel_id"];
  if (typeof channelId !== "string") throw new Error("channel_id required");
  return plugin.db.query("SELECT * FROM messages WHERE channel_id = ?", [channelId]);
});
```

## events

Durable, acked, at-least-once event bus with per-(topic, subscriber) FIFO
ordering. Requires `events.publish` / `events.subscribe` capabilities.

```ts
plugin.events.publish(topic: string, payload: unknown, version?: number): void
plugin.events.subscribe(topic: string, handler: (event) => void, options?: SubscribeOptions): Promise<void>
plugin.events.unsubscribe(topic: string): Promise<void>
```

`SubscribeOptions`: `{ overflow_policy?: "mark_unhealthy" | "drop_oldest" | "drop_newest"; queue_size?: number }`.
Default backpressure is `mark_unhealthy` (failures are loud). The handler
receives an `event` with `{ topic, payload, version, ts, source_plugin }`. See
[Data & events](/guide/data-and-events#event-bus-durable-acked-plugin-to-plugin).

## db

The plugin's own SQLite. Requires `data.sql:self`.

```ts
plugin.db.query<T>(sql, params?): Promise<T[]>                 // SELECT → rows
plugin.db.run(sql, params?): Promise<{ changes, lastInsertRowid }>  // INSERT/UPDATE/DELETE
plugin.db.exec(sql): Promise<void>                             // DDL / PRAGMA
plugin.db.batch(statements): Promise<RunResult[]>              // atomic multi-statement
```

Always pass values via `?` placeholders. Use `batch()` when writes must commit
together. Schema is built by [migrations](/guide/plugin-anatomy#migrations).

## kv

String key/value backed by a `_kv` table in your SQLite. Requires `data.kv:self`.
Values are **always strings** — `JSON.stringify` complex values.

```ts
plugin.kv.get(key): Promise<string | null>
plugin.kv.set(key, value): Promise<void>
plugin.kv.delete(key): Promise<void>
plugin.kv.list(prefix?): Promise<{ key, value }[]>   // ordered by key
plugin.kv.getMany(keys): Promise<Record<string, string>>  // one round-trip
```

## settings

Read this plugin's admin-configurable settings (declared in `manifest.settings`)
and react to admin changes. **No capability required.**

```ts
plugin.settings.get(key): Promise<string | number | boolean>     // stored value or manifest default
plugin.settings.getAll(): Promise<Record<string, string | number | boolean>>
plugin.settings.onChange(handler: (ev: { key, value }) => void): () => void
```

`get` throws `UNKNOWN_SETTING` for an undeclared key. `onChange` fires once per
admin config save while the plugin runs; returns a disposer.

## broadcast

Push to connected WebSocket clients. Fire-and-forget, not durable. Requires
`broadcast.clients`. The runtime namespaces the event with your slug; the
frontend SDK strips it (so backend `"x"` ↔ frontend `sdk.on("x", …)`).

```ts
plugin.broadcast.toUser(userId, event, payload): Promise<void>
plugin.broadcast.toUsers(userIds, event, payload): Promise<void>   // ≤ 100 ids
plugin.broadcast.toAll(event, payload): Promise<void>
```

## presence

Connect/disconnect hooks (no capability) plus scoped ephemeral presence (folded
under `broadcast.clients`).

```ts
plugin.presence.onConnected(handler: (user) => void): () => void
plugin.presence.onDisconnected(handler: (user) => void): () => void

plugin.presence.join(scope, userId, meta?): Promise<() => Promise<void>>   // returns a leave fn
plugin.presence.leave(scope, userId): Promise<void>
plugin.presence.update(scope, userId, meta): Promise<void>                 // never implicitly joins
plugin.presence.watch(scope, cb: (entries) => void, { coalesceMs? }): Promise<() => void>  // default 50ms, clamps [0,500]
plugin.presence.list(scope): Promise<PresenceEntry[]>
```

Scopes are auto-prefixed with your slug — don't add the prefix yourself.
`join`/`leave`/`update` infer the originating WS session from request context, so
they must be called **inside a request handler** (they throw
`PRESENCE_NO_SESSION_CONTEXT` from a schedule tick or cross-plugin event handler).

## schedule

Recurring tasks. Requires `runtime.schedule`. Schedules are named; re-registering
a name replaces it. Minimum interval 1000ms.

```ts
plugin.schedule.every(name, intervalMs, handler: (tick) => void, options?): Promise<void>
plugin.schedule.cancel(name): Promise<void>
```

`options.timeout_ms` (default 30000) bounds how long the handler may block the
IPC slot per tick; on timeout the tick resolves with an error but the handler
keeps running in the background.

## fetch

Outbound HTTP via the runtime proxy. Requires `http.fetch:<hostname>` for each
host. Redirects are **never** followed (a 3xx is returned as-is).

```ts
const res = await plugin.fetch(url, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ … }),   // string only; base64-encode binary yourself
});
res.status;           // number
res.headers;          // Record<string, string>
res.text();           // sync — body is pre-buffered
res.json<T>();        // sync
res.bytes();          // Uint8Array, sync
```

`.text()`/`.json()`/`.bytes()` are synchronous because the IPC round-trip already
buffered the full body.

## core

Read the Core Module's user-profile and category cache. **No capability
required.**

```ts
plugin.core.getUser(userId): Promise<CoreUser | null>
plugin.core.getUsers(userIds): Promise<CoreUser[]>           // missing ids omitted
plugin.core.getOnlineUsers(): Promise<CoreUser[]>
plugin.core.listCategories(): Promise<CoreCategory[]>        // admin-managed; reference by id (soft FK)
```

## data

Cross-plugin reads against another plugin's `public_schema`. Requires
`data.read:<plugin>.<table>`. Immutable builder — each method returns a new query.

```ts
const rows = await plugin.data
  .read<RowType>("text-channels", "messages")
  .where("channel_id", "=", id)
  .select(["id", "content", "created_at"])
  .orderBy("created_at", "desc")
  .limit(50)
  .exec();
```

Only published columns are selectable/filterable; the target DB is read-only.

## permissions

Your plugin's checks on its **users** (roles and plugin-defined permissions).
This is application logic — no manifest capability gates it.

```ts
plugin.permissions.register(key, { description, default_level }): Promise<void>
plugin.permissions.check(userId, permission, scope?): Promise<boolean>
plugin.permissions.hasRole(userId, roleName): Promise<boolean>
plugin.permissions.hasMinLevel(userId, level): Promise<boolean>
plugin.permissions.getRole(userId): Promise<{ name, level }>
plugin.permissions.canActOn(actorId, targetId): Promise<boolean>   // rank check for moderation
```

Register custom permission keys at startup; gate handlers with `check` /
`hasMinLevel`. Role levels are numeric (higher = more privileged).

## resources

Plugin resource permissions (per-resource ACLs). The runtime stamps your slug on
every define/create/grant/revoke, so you can only manage your **own** resources.
Cross-plugin `check` requires `resources.read:<owner-plugin>`.

```ts
plugin.resources.define({ resourceType, … }): Promise<void>
plugin.resources.create({ resourceType, resourceId, parent?, owner? }): Promise<PluginResourceRef>
plugin.resources.grant(resource, principal, action): Promise<{ aclVersion }>
plugin.resources.revoke(resource, principal, action): Promise<{ aclVersion }>
plugin.resources.check(userId, resource, action): Promise<AuthDecision>
```

The runtime returns `PLUGIN_RESOURCES_UNAVAILABLE` if booted without the resource
backend.

## files

Plugin file storage — the plugin's own `<dataDir>/uploads/`. Requires
`storage.file:self`. Clients POST to `/upload` directly; the runtime then fires
the `onFileUploaded` callback you pass to `createPlugin`. Use this API to
stat/sign/delete those files.

```ts
plugin.files.stat(filename): Promise<{ exists, size, mtime }>
plugin.files.signUrl(filename, userId, ttlSeconds?): Promise<{ url, exp }>  // default 1h, max 24h
plugin.files.delete(filename): Promise<{ deleted: boolean }>
plugin.files.list(): Promise<{ filename, size, mtime }[]>
```

`signUrl` returns a path-only URL (no host) bound to `userId`; the client
prefixes its current server origin so the URL survives tunnel hostname changes.

```ts
const plugin = createPlugin({
  onFileUploaded(msg) {
    // msg: { filename, path, size, mimeType, uploadedBy, uploadedAt }
  },
});
```

## voice

Voice bridge (LiveKit). Per-method capabilities; the runtime returns
`VOICE_BRIDGE_UNAVAILABLE` if booted without voice support.

```ts
// Capability: voice.tokens:self
plugin.voice.createJoinToken({ channelId, userId, grants?, canPublishSources? }): Promise<VoiceJoinToken>
// Capability: voice.moderation:self
plugin.voice.removeParticipant({ channelId, userId, reason? }): Promise<{ ok: true }>
```

`createJoinToken` returns `{ token, livekitUrl, expiresAt }`. The plugin is
responsible for ACL checks (channel exists, user not banned, role gate) before
minting. **Derive `canPublishSources` from the user's permissions** — never pass
client-supplied values through.

## serveReady

```ts
plugin.serveReady(): void
```

Signal that internal state is hydrated and the plugin can serve user requests.
Effective only when the manifest sets `serve_ready_handshake: true`; otherwise a
harmless no-op. See [Lifecycle](/guide/lifecycle#the-optional-serve-ready-handshake).

## errors

```ts
import { SdkError, SdkProtocolError } from "@uncorded/plugin-sdk";
```

Every error thrown across the SDK boundary is an `SdkError` (or subclass) with a
stable machine-readable `.code` and optional `.context`. `SdkProtocolError`
(a subclass) signals the runtime returned an error response or a payload that
didn't match the expected shape. Catch on `.code`, never on message text.

## request context

```ts
import { getCurrentSession, getRequestContext } from "@uncorded/plugin-sdk";
```

Inside a request handler, `getCurrentSession()` returns the originating WS
session id (or `undefined` for runtime-originated calls like a schedule tick).
This is the mechanism `presence.join/leave/update` use to attribute themselves to
the right session.

---

---
url: /reference/frontend-sdk.md
---
# Frontend SDK reference

`@uncorded/plugin-sdk-frontend`. The browser side of a plugin — the code that
runs inside the sandboxed iframe the shell renders for your panel. It talks to
your backend over the shell via `postMessage`, never directly. Source of truth:
[`packages/plugin-sdk-frontend/src`](https://github.com/UnCorded/uncorded-platform/blob/main/packages/plugin-sdk-frontend/src).

## Loading the SDK

The runtime serves a prebuilt IIFE bundle at `/sdk/plugin-frontend.js`. Load it
with a classic `<script>` tag (not a module import) — a sandboxed iframe has an
opaque origin, and a classic `<script src>` is a no-CORS fetch that loads
regardless. The bundle sets `window.UncodedPlugin`:

```html
<script src="/sdk/plugin-frontend.js"></script>
<script>
  (async () => {
    const sdk = await window.UncodedPlugin.createPluginFrontend();
    const entries = await sdk.request("listEntries");
    // … render …
  })();
</script>
```

`window.UncodedPlugin` exposes `createPluginFrontend` plus the avatar helpers
(`createAvatar`, `avatarHtml`, `avatarColor`, `avatarInitial`, `isSafeAvatarUrl`).
If you bundle your frontend instead, `import { createPluginFrontend } from
"@uncorded/plugin-sdk-frontend"` works too.

## createPluginFrontend

```ts
const sdk = await createPluginFrontend(options?: { handshakeTimeoutMs?: number });
```

Performs the shell handshake and resolves to a fully-initialized
`PluginFrontend`. **`await` it before calling anything else.**

### The handshake

On call the SDK derives the shell origin from `document.referrer`, posts
`uncorded.ready` (carrying its `SDK_API_VERSION`) to the parent, and waits for
the shell's `uncorded.token` reply (`{ token, slug, runtimeCapabilities,
itemId?, itemLabel? }`). Default timeout **5000ms** — override with
`handshakeTimeoutMs`. Failure throws a [`PluginError`](#errors) with code
`HANDSHAKE_FAILED` (no resolvable referrer — i.e. not running inside a shell) or
`HANDSHAKE_TIMEOUT`. Every subsequent inbound message is origin-checked against
the verified shell origin; every outbound message is targeted at it (never `*`).

## slug / token

```ts
sdk.slug;   // string — this plugin's slug, assigned by the runtime
sdk.token;  // string — the session bearer token (used by files/proxy internally)
```

## request

```ts
sdk.request<T>(action: string, params?: Record<string, unknown>): Promise<T>
```

Calls a backend [`plugin.handle(action, …)`](/reference/backend-sdk#handle-request)
and resolves with its return value. Correlated by id over `postMessage`.
**Timeout 30s** → rejects with `PluginError` code `REQUEST_TIMEOUT`; a backend
error rejects with that error's `.code`.

```ts
const messages = await sdk.request("getMessages", { channel_id: id });
```

## subscribe (event bus)

```ts
sdk.subscribe<T>(topic: string, handler: (payload: T) => void): () => void
```

Subscribe to a server-side **event-bus** topic (the same topics the backend
[`events`](/reference/backend-sdk#events) bus carries, e.g.
`"text-channels.message.created"`). Sends a `subscribe` message to the shell so
the runtime routes matching events to this iframe. Returns an unsubscribe
function.

## on (broadcasts)

```ts
sdk.on<T>(event: string, handler: (payload: T) => void): () => void
```

Receive **broadcasts** pushed from your backend via
[`plugin.broadcast`](/reference/backend-sdk#broadcast). The slug prefix is
stripped transparently: the backend sends `broadcast.toAll("entry.added", …)`
(on the wire `"<slug>.entry.added"`) and you write:

```ts
sdk.on("entry.added", (entry) => { /* prepend to the list */ });
```

No subscribe message is sent — broadcasts are pushed directly to the WS
connection and the shell routes all your slug-prefixed events here. Returns an
unsubscribe function.

> **subscribe vs on:** `subscribe` = durable event-bus topics (cross-plugin,
> runtime). `on` = your backend's fire-and-forget UI pushes. Most live-UI
> updates use `on`.

## onNavigate

```ts
sdk.onNavigate(handler: (nav: { itemId: string; itemLabel: string }) => void): () => void
```

Fires when the user selects one of your sidebar items. If the iframe opened
*onto* an item, the handler is invoked once on registration (next microtask)
with the initial navigation, so you don't miss the first selection. Returns an
unsubscribe function.

```ts
sdk.onNavigate(({ itemId }) => loadChannel(itemId));
```

## files

```ts
sdk.files.upload(file: Blob | File, options?: UploadOptions): Promise<UploadResult>
```

Uploads a user-selected file to **your** plugin's storage (the runtime's
`POST /upload`, authed with the session token and pinned to your slug — the
backend needs [`storage.file:self`](/reference/permissions)). The server picks
the on-disk filename; pass the returned `filename` back through your backend to
record it.

```ts
const res = await sdk.files.upload(file, {
  onProgress: ({ ratio }) => setBar(ratio),
  signal: controller.signal,
  maxBytes: 25 * 1024 * 1024,
});
// res: { filename, size, mime, originalName }
```

* `UploadResult`: `{ filename, size, mime, originalName }`.
* `UploadProgress`: `{ loaded, total, ratio }` (~10 Hz).
* Files ≤ 50 MB go single-shot; larger use resumable chunked upload (5 GB hard
  ceiling, set by the runtime).
* Failures throw [`UploadError`](#errors) with a `.code` (`ABORTED`,
  `PAYLOAD_TOO_LARGE`, `UNAUTHORIZED`, `FORBIDDEN`, `RATE_LIMITED`,
  `NETWORK_ERROR`, `TIMEOUT`, `UPLOAD_EXPIRED`, `INTEGRITY_FAILED`, …).

The backend's [`onFileUploaded`](/reference/backend-sdk#files) callback fires
once the upload lands, so the backend can record it in its own DB.

## proxy

Two ways to render a proxied mount. They differ in **who owns the surface** —
your iframe, or the shell. Pick one per panel; don't combine them for the same
mount. Full guide, including which to choose: [Reverse-proxy plugins](/sdk/reverse-proxy#two-ways-to-render-a-mount).

```ts
sdk.proxy.openMount(mount: string): Promise<{ iframeUrl: string; openUrl: string }>
```

**Self-embed.** *Your* panel owns a nested `<iframe>`. Bootstraps a manifest
[`proxy_mounts`](/reference/manifest#proxy_mounts) entry: mints the proxy-session
cookie and returns `iframeUrl` (set as the iframe `src`) and `openUrl` (an "Open
in browser" fallback, required under Safari ITP). Same render on desktop and web.
Fails when the upstream blocks framing (`X-Frame-Options: DENY` /
restrictive `frame-ancestors` CSP). Throws [`ProxyError`](#errors) (`NOT_FOUND`,
`NOT_APPROVED`, `FORBIDDEN`, `UNAUTHORIZED`, `RATE_LIMITED`, …). **Not for
`fetch()`-driven WebGL/canvas apps** (Foundry VTT, maps): textures fetched
credentialed from this sandboxed `null`-origin iframe are CORS-blocked and the
canvas stays blank — use `reserveMount`.

```ts
sdk.proxy.reserveMount(mount: string, el: HTMLElement): () => void
```

**Host-owned surface.** The *shell* renders the proxied app over a placeholder
element you supply: a dedicated, hardened Electron `<webview>` on **desktop**
(escapes `X-Frame-Options`/`frame-ancestors`, isolated per-server session, native
permission prompts), a sandboxed `<iframe>` on **web**. You pass the placeholder;
the SDK reports its layout rect to the shell (rAF-coalesced, tracks scroll/resize)
and the shell bootstraps the session and positions the surface over it. Synchronous
— it returns an **idempotent dispose function**; call it (or let the panel unmount)
to release the viewport. Bootstrap/`ProxyError` failures surface in the shell-owned
surface (e.g. an "Open in browser" prompt on web), not as a throw here. **Required
for `fetch()`-driven WebGL/canvas apps** (Foundry VTT, maps): the host surface has
a real origin, so credentialed texture fetches load same-origin with no CORS wall —
the case `openMount` can't render.

## platform

Shell-mediated UI capabilities. None require a manifest capability (except voice,
gated by `runtime_capabilities`) — the shell decides whether to honor each.

### platform.panels

```ts
sdk.platform.panels.open(options: {
  itemId: string; itemLabel: string; itemIcon?: string;
  placement?: "beside-current" | "replace-current";
  mode?: "reuse-or-create" | "new";
}): void
sdk.platform.panels.focusCurrent(): void
```

Ask the shell to open another panel for **this same plugin** (the new iframe gets
`itemId`/`itemLabel` via `onNavigate`), or focus/fullscreen the current one.

### platform.userCard

```ts
sdk.platform.userCard.show({ userId: string; displayName?: string; avatarUrl?: string | null }): void
```

Surface the shell's rich user card. Wire it to avatar clicks so every plugin gets
the same card UX for free.

### platform.files

```ts
sdk.platform.files.preview({ url: string; name: string }): void
sdk.platform.files.download({ url: string; name: string }): void
```

Open the shell's file-preview overlay, or trigger a native download. URLs are
pinned to your runtime origin. Use these instead of an in-iframe `<a download>`,
which is unreliable cross-origin and on Linux Electron.

### platform.voice

The iframe side of the `platform.voice.*` postMessage contract. The shell owns
the LiveKit room and pushes state in; the plugin posts user intent back. The
plugin never imports `livekit-client` or touches `getUserMedia`. Gated by
`runtime_capabilities` (declared in the manifest) — read the grant flags before
rendering affordances:

```ts
const v = sdk.platform.voice;
v.granted;             // voice.media granted?
v.screenShareGranted;  // voice.screen_share granted?
v.moderationGranted;   // voice.moderation granted?
```

Intent methods (fire-and-forget): `connect({ channelId, channelName? })`,
`disconnect()`, `setMicMuted(muted)`, `setLocalParticipantMuted({ userId, muted })`,
`setLocalParticipantVolume({ userId, volume })`, `setDeafened(deafened)`,
`startAudio()` (call from a click handler to unblock autoplay),
`startScreenShare({ audio, quality, sourceId? })`, `stopScreenShare()`,
`setScreenShareQuality(q)`, `subscribeScreenShare(sid)` /
`unsubscribeScreenShare(sid)`, `popoutScreenShare(sid)` / `dockScreenShare(sid)`,
`setScreenShareVolume(sid, pct)`, `muteScreenShareAudio(sid, muted)`,
`adminStopScreenShare({ channelId, userId, reason? })`,
`observeScreenSlot(el, trackSid, slotId)` (returns a dispose fn).

State pushes (each returns an unsubscribe fn): `onState(state)`,
`onParticipants(list)`, `onActiveSpeakers(ids)` (throttled ≤5/s), `onError(err)`,
`onScreenShareSubscriptions(subs)`, `onScreenSharePopouts(popouts)`.

Voice is a large subsystem; the canonical consumer is the `voice-channels`
plugin frontend.

## Avatar helpers

Framework-agnostic, safe in vanilla iframes. Color and initial are deterministic
from `userId`, so the runtime, shell, and every plugin pick the same hue:

```ts
const { createAvatar, avatarHtml, avatarColor, avatarInitial, isSafeAvatarUrl } = window.UncodedPlugin;

container.appendChild(createAvatar({ userId, displayName, avatarUrl, size: 32, shape: "circle" }));
el.innerHTML = avatarHtml({ userId, displayName });   // string form
```

`isSafeAvatarUrl(url)` returns true only for `http(s)` — use it before trusting a
user-supplied avatar URL.

## errors

| Class | Thrown by | Notable `.code`s |
| --- | --- | --- |
| `PluginError` | `createPluginFrontend`, `request` | `HANDSHAKE_FAILED`, `HANDSHAKE_TIMEOUT`, `REQUEST_TIMEOUT`, `REQUEST_FAILED` (or the backend's code) |
| `UploadError` | `files.upload` | `ABORTED`, `PAYLOAD_TOO_LARGE`, `UNAUTHORIZED`, `FORBIDDEN`, `RATE_LIMITED`, `NETWORK_ERROR`, `TIMEOUT`, `UPLOAD_EXPIRED`, `INTEGRITY_FAILED` |
| `ProxyError` | `proxy.openMount` | `INVALID_ARGUMENT`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `NOT_APPROVED`, `RATE_LIMITED`, `NETWORK_ERROR`, `MALFORMED_RESPONSE`, `BOOTSTRAP_FAILED` |

All three carry a string `.code`; `UploadError`/`ProxyError` also carry `.status`
(HTTP status or `null`). Catch on `.code`, never message text.

## SDK\_API\_VERSION

```ts
import { SDK_API_VERSION } from "@uncorded/plugin-sdk-frontend";  // "1.1"
```

The iframe ships this in `uncorded.ready` so the shell can detect a stale iframe
HTML / SDK bundle mismatch and hard-reload both. Manifests declare a compatible
range via `api_version` (e.g. `^1.0`). MINOR bumps are additive; MAJOR bumps are
breaking and coordinated with a runtime + manifest bump.

---

---
url: /reference/ipc-protocol.md
---
# IPC protocol

How the runtime and a plugin backend talk. You never write this by hand — the
[backend SDK](/reference/backend-sdk) speaks it for you — but understanding the
wire format makes logs, timeouts, and size limits legible. Source of truth:
[`runtime/src/ipc`](https://github.com/UnCorded/uncorded-platform/blob/main/runtime/src/ipc)
and the schemas in
[`packages/protocol-schemas/src/index.ts`](https://github.com/UnCorded/uncorded-platform/blob/main/packages/protocol-schemas/src/index.ts).

## Transport — stdio, newline-delimited JSON

Each plugin runs as a subprocess. The runtime owns its `stdin`/`stdout`; the
channel is **newline-delimited JSON over stdio** — one JSON object per line.

* **Plugin → runtime:** stdout lines **prefixed with `IPC:`** are protocol
  messages (`IPC:{"type":"ready"}`). Any other stdout line, and **all stderr**,
  is captured by the runtime's log collector. So `console.error(...)` from a
  plugin shows up in runtime logs; it never corrupts the protocol.
* **Runtime → plugin:** plain JSON lines on the plugin's stdin.
* **Don't read stdin** or write raw `IPC:` lines yourself — the transport owns
  both.

### Size limit

A single IPC line is capped at **`MAX_IPC_LINE_BYTES` = 4 MB**. Consequences:

* An inbound line that exceeds 4 MB with no newline is a fatal framing error —
  the runtime kills the subprocess (a plugin can't be allowed to exhaust memory
  buffering one unbounded line).
* A handler **response** is bounded to slightly under 4 MB (4 MB minus envelope
  headroom). Exceed it and the SDK surfaces a catchable `RESPONSE_TOO_LARGE`
  error instead of silently dropping the reply. Paginate or stream large results
  (e.g. cap a list query and pass a cursor) rather than returning everything.

## Message envelope

Every message is an object with a string `type`. Request/response-style messages
also carry a string `id` used to correlate a reply with its request. Beyond
those two fields the envelope is open — actions add their own params without
changing the protocol.

## Runtime → plugin frames

The SDK dispatcher routes exactly these `type`s
(`RuntimeToPluginMessageSchema`); anything else is silently ignored, so adding a
new runtime frame never breaks an old plugin:

| `type` | Meaning | Key fields |
| --- | --- | --- |
| `request` | A user/caller is invoking one of your [`handle`](/reference/backend-sdk#handle-request) actions. | `id`, `action`, `params`, `user` `{id, displayName, avatarUrl, role}`, `session_id?` |
| `response` | The runtime's reply to a service call **you** made (db, kv, fetch, …). | `id`, `result?`, `error?` |
| `event.ack` | Acknowledges an [`events.publish`](/reference/backend-sdk#events) / subscribe. | `id`, `ok`, `event_id?`, `error?` |
| `event.deliver` | An event-bus delivery to one of your subscriptions. | `topic`, `version`, `id`, `ts`, `source_plugin`, `payload` |
| `ping` | Watchdog heartbeat. SDK auto-replies `pong`. | — |
| `file.uploaded` | A client finished uploading to your `/upload`. Fires `onFileUploaded`. | `filename`, `path`, `size`, `mimeType`, `uploadedBy`, `uploadedAt` |
| `core.plugin.config_changed` | An admin changed one of your settings. Fires `settings.onChange`. | `key`, `value`, `changed_by_user_id`, `ts` |

## Plugin → runtime frames

The SDK sends these on your behalf. The lifecycle/heartbeat frames:

| `type` | When |
| --- | --- |
| `ready` | Sent by `createPlugin()` once the SDK is wired — the [ready handshake](/guide/lifecycle#the-ready-handshake). |
| `serve_ready` | Sent by [`serveReady()`](/reference/backend-sdk#serveready) when caches are warm (opt-in). |
| `pong` | Auto-reply to each `ping`. |
| `response` | Your handler's result for an inbound `request`. |

Everything else a plugin sends is a **typed service call** — a request/response
pair where the `type` names the runtime service and the runtime replies with a
`response` carrying the same `id`. These map one-to-one onto SDK methods, e.g.
`data.sql` ([`db`](/reference/backend-sdk#db)), `data.kv`
([`kv`](/reference/backend-sdk#kv)), `data.read`, `events.publish` /
`events.subscribe` / `events.unsubscribe`, `broadcast.toAll` /
`broadcast.toUsers`, `http.fetch` ([`fetch`](/reference/backend-sdk#fetch)),
`schedule.register`, `presence.*`, `permissions.*`, `resources.*`,
`storage.file`, `voice.tokens` / `voice.moderation`, `core.*`. Use the SDK — the
frame names are an implementation detail listed here only for log-reading.

## Capability enforcement

Every typed service call is checked against the plugin's manifest
[`permissions`](/reference/permissions) **at the runtime boundary**, before the
service runs. An undeclared capability is a **hard reject** — the call comes back
as an error `response`, never a partial result. There is no per-call override:
if it isn't in the manifest, it cannot happen. This is why the
[permissions reference](/reference/permissions) maps each SDK feature to its
exact capability string.

## Error envelope

An error `response` carries a structured error, not a bare string:

```json
{ "type": "response", "id": "…", "error": { "code": "PERMISSION_DENIED", "message": "…", "context": { } } }
```

The SDK rethrows this as an [`SdkError`](/reference/backend-sdk#errors) whose
`.code` equals the envelope `code`. Always branch on `.code`; the `message` is
for humans and the `context` is optional diagnostic detail.

## See also

* [Lifecycle](/guide/lifecycle) — where `ready`/`ping`/`pong` sit in the boot and
  watchdog flow, and the message-frames table in context.
* [Backend SDK](/reference/backend-sdk) — the methods these frames implement.

---

---
url: /sdk/reverse-proxy.md
---
# Reverse-proxy plugins

A reverse-proxy plugin lets an UnCorded server expose a **self-hosted web app**
(a "upstream") to its members through the runtime's reverse proxy, behind a
sidebar panel. The canonical example is [Foundry VTT](https://github.com/UnCorded/uncorded-platform/tree/main/plugins/foundry-vtt):
a sidebar entry whose panel loads a proxied Foundry server in an iframe.

## Mental model

The proxy is **runtime-owned**. Your plugin never proxies bytes itself. You:

1. **Declare** one or more `proxy_mounts` in the manifest, each pointing at a
   setting that holds the upstream URL.
2. **Surface** a sidebar item from the backend (a few lines — no proxy logic).
3. **Render** the mount from the frontend panel. Two choices, covered in
   [Two ways to render a mount](#two-ways-to-render-a-mount): let the **host**
   render it in its own surface — `sdk.proxy.reserveMount(name, el)`, a hardened
   `<webview>` on desktop / sandboxed `<iframe>` on web — or **self-embed** a
   nested iframe yourself — `sdk.proxy.openMount(name)`.

The runtime handles approval gating, session cookies, access policy, and the
actual HTTP/WebSocket forwarding under `/proxy/<slug>/<mount>/*`.

```
manifest proxy_mount ──▶ owner approves ──▶ runtime serves upstream
   (upstream_setting)     (Server settings)    /proxy/<slug>/<mount>/*
        │                                              ▲
        ▼                                              │
   backend: sidebar item ──▶ frontend: reserveMount() / openMount()
```

> The backend SDK has **no** proxy API. Don't look for `createProxyMount()` —
> everything proxy-related is declared in the manifest and driven from the
> frontend.

***

## 1. Manifest

Source of truth: [`packages/shared/src/manifest.ts`](https://github.com/UnCorded/uncorded-platform/blob/main/packages/shared/src/manifest.ts).
A reverse-proxy-only plugin is `type: "standalone"` (it owns no data and runs no
logic of its own).

```json
{
  "name": "proxy-demo",
  "version": "0.1.0",
  "api_version": "^1.0",
  "author": "you",
  "description": "Proxy a self-hosted app into the UnCorded sidebar.",
  "license": "MIT",
  "type": "standalone",
  "icon": "Globe",
  "backend": { "entry": "backend/index.ts" },
  "frontend": { "entry": "frontend/index.html" },
  "permissions": ["proxy.http:self", "proxy.websocket:self"],
  "sidebar": { "contributes": true, "section": "Apps" },
  "settings": [
    {
      "key": "demo_upstream_url",
      "label": "Upstream URL",
      "description": "Base URL of the app to proxy. For a host app from the Docker runtime use http://host.docker.internal:<port>.",
      "type": "string",
      "default": "http://host.docker.internal:3011",
      "required": true
    }
  ],
  "proxy_mounts": [
    { "name": "demo", "upstream_setting": "demo_upstream_url", "access": "members" }
  ]
}
```

### Top-level fields (required unless noted)

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string | Lowercase slug. This is the plugin's slug everywhere (`installed_plugins`, URLs, the install folder name). |
| `version` | string | Semver `MAJOR.MINOR.PATCH`. |
| `api_version` | string | Semver range, e.g. `^1.0`. |
| `author`, `description` | string | Human-readable. |
| `type` | `"standalone"` | `"core"` | `"extension"` | Proxy-only plugins are `standalone`. `extension` also needs `extends`. |
| `permissions` | string\[] | Must include the proxy permission(s) — see below. |
| `backend` / `frontend` | `{ entry }` | At least one required; a proxy panel needs **both**. |
| `settings` | array | Declares the upstream setting(s) referenced by mounts. |
| `proxy_mounts` | array | The mounts. Non-empty when present. |
| `sidebar` | `{ contributes, section, ... }` | Set `contributes: true` to show a sidebar item. |
| `license`, `icon` | string | Optional. `icon` is a lucide icon name. |

### `proxy_mounts[]`

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string | Slug-safe and unique within the plugin: lowercase, **starts with a letter**, hyphen-separated segments (`[a-z][a-z0-9]*(-[a-z0-9]+)*` — no leading/trailing or doubled hyphens). Appears in the URL: `/proxy/<slug>/<name>/*`. |
| `upstream_setting` | string | **Key of a setting in this same manifest** (type `string` or `secret`) whose value is the upstream URL. The manifest never carries the URL directly. |
| `access` | `"members"` | `"owner"` | Optional, defaults to `"members"`. `owner` restricts the mount to the server owner/admins. |
| `max_frame_bytes` | integer | Optional. Caps the size of a single **WebSocket** frame relayed in either direction (bytes). Defaults to **65536** (64 KiB); raise it for sockets that bulk-sync. Range **1024**–**16777216** (1 KiB–16 MiB). See [Real-time apps (WebSockets)](#real-time-apps-websockets). |

### Permissions

Declare what the mount needs — **WebSocket is not implied by HTTP**:

* `proxy.http:self` — forward HTTP requests to the upstream.
* `proxy.websocket:self` — forward WebSocket upgrades (needed for live apps,
  hot-reload, game sockets, etc.).

Validation rejects a manifest that declares `proxy_mounts` without at least one
of these permissions.

***

## 2. Backend

The backend is tiny: register a sidebar item. No proxy code.

```ts
// backend/index.ts
import { createPlugin } from "@uncorded/plugin-sdk";

const plugin = createPlugin();

plugin.handle("sidebar.items", async () => ({
  items: [
    {
      id: "demo",
      label: "Proxy Demo",
      icon: "Globe",
      panelType: "plugin" as const,
      slug: "proxy-demo",   // must equal manifest "name"
      section: "Apps",
    },
  ],
}));
```

`createPlugin()` returns a `PluginHandle` with the full backend surface
(`handle`, `request`, `events`, `db`, `kv`, `settings`, `broadcast`,
`presence`, `fetch`, …) — but a proxy-only plugin uses none of it beyond
`handle("sidebar.items", …)`.

### Packaging — backends run as subprocesses

The runtime executes each backend as its **own subprocess** with the plugin
directory as the working directory (`Bun.spawn(["bun","--smol","run", entry], { cwd: pluginPath })` —
see [`runtime/src/subprocess.ts`](https://github.com/UnCorded/uncorded-platform/blob/main/runtime/src/subprocess.ts)).
That means:

* Any `import` (e.g. `@uncorded/plugin-sdk`) is resolved against the plugin's
  **own `node_modules`**. The runtime does **not** run `bun install` / `npm install`
  on your plugin.
* **Package your plugin with its dependencies present** — ship `node_modules`
  in the installed folder, or include a `package.json` + lockfile and install
  into the folder before installing the plugin.

> A backend that imports nothing (raw stdio only) will load without packaging,
> but real plugins use the SDK and therefore must be packaged with deps. Don't
> ship an SDK-importing backend without its `node_modules`.

***

## 3. Frontend

The panel HTML loads the frontend SDK and renders the mount. **First decide how
the proxied app is rendered** — that choice drives the rest of the panel.

### Two ways to render a mount

`sdk.proxy` offers two render models, differing in **who owns the surface** the
upstream loads into. Use one per panel.

| | `openMount` — self-embed | `reserveMount` — host-owned surface |
| --- | --- | --- |
| Who renders | **your** panel owns a nested `<iframe>` | the **shell** renders the surface; you only reserve a rect |
| Desktop (Electron) | a nested `<iframe>` | a dedicated **hardened `<webview>`** — escapes `X-Frame-Options`/`frame-ancestors`, isolated per-server session, native permission prompts, navigation pinned to the mount |
| Web (browser) | a nested `<iframe>` | a host-owned **sandboxed `<iframe>`** + "Open in browser" fallback |
| Framing-hostile upstream (`X-Frame-Options: DENY`, strict `frame-ancestors`) | ❌ won't load (especially on desktop) | ✅ loads on desktop; web shows the open-in-browser prompt |
| `fetch()`-driven **WebGL/canvas** app (Foundry VTT, maps) | ❌ canvas stays blank — null-origin texture CORS (see below) | ✅ real-origin surface, textures load same-origin |
| You get back | `{ iframeUrl, openUrl }` (async) | an idempotent dispose function (sync) |
| Failures | throws `ProxyError` you handle | surfaced in the shell-owned UI |

**Which to use:**

* Reach for **`reserveMount`** when the upstream refuses to be framed, when you
  want camera/mic/location behind a real permission prompt, or simply to get the
  best desktop experience. This is the recommended default for "load a whole
  self-hosted app" panels (Foundry VTT, dashboards, admin panels).
* Reach for **`openMount`** when you want your panel to own the iframe directly —
  to overlay your own chrome, read load events, or embed a cooperative app that
  frames fine. Simpler, but desktop gets a plain iframe and a framing-hostile
  upstream won't load.

> ⚠️ **`reserveMount` is REQUIRED for `fetch()`-driven WebGL/canvas apps**
> (Foundry VTT, map/whiteboard/streaming-tile tools). These apps load their
> textures with credentialed `fetch()`. `openMount` self-embeds them in your
> panel's **sandboxed `null`-origin iframe**, and a credentialed fetch from a
> `null` origin needs `Access-Control-Allow-Origin: null` — which Chromium
> **hard-blocks**. The result: the frame loads, the page renders its chrome, but
> the canvas stays **blank**, with no error the shell can detect. There is no
> upstream header or CORS config that fixes this for `openMount`; the only fix is
> a real-origin surface, which is exactly what `reserveMount` provides (an
> Electron `<webview>` on desktop, a host-managed `<iframe>` on web). On web,
> `reserveMount` also keeps a persistent **"Open in browser"** affordance on the
> surface, because a browser tab is a real top-level origin and is the most
> reliable way for web users to view a heavy canvas app.

Both honor the same manifest, permissions, and [approval](#approval-mounts-fail-closed);
only the render surface differs. The runtime routes and headers in sections 5–7
below apply identically to both.

### Option A — self-embed with `openMount`

*Your* panel owns a nested iframe, sets its `src`, and shows an "Open in browser"
fallback. Adapted from [`plugins/foundry-vtt/frontend`](https://github.com/UnCorded/uncorded-platform/tree/main/plugins/foundry-vtt/frontend):

```html
<!-- frontend/index.html -->
<body>
  <p id="status">Connecting…</p>
  <iframe id="frame" allow="fullscreen; clipboard-read; clipboard-write" title="Proxy Demo"></iframe>
  <div id="fallback" hidden>
    <span>Trouble loading?</span>
    <a id="open-link" target="_blank" rel="noreferrer">Open in browser</a>
  </div>

  <!-- Served by the runtime; do not bundle it yourself. -->
  <script src="/sdk/plugin-frontend.js"></script>
  <script type="module">
    const MOUNT = "demo"; // must equal a proxy_mounts[].name

    const sdk = await window.UncodedPlugin.createPluginFrontend();
    const status = document.getElementById("status");
    const frame = document.getElementById("frame");
    const link = document.getElementById("open-link");
    const fallback = document.getElementById("fallback");

    try {
      const session = await sdk.proxy.openMount(MOUNT);
      frame.src = session.iframeUrl;     // proxied URL, cookie already minted
      link.href = session.openUrl;       // first-party "Open in browser" fallback
      status.hidden = true;
      fallback.hidden = false;
    } catch (err) {
      // err is a ProxyError — err.code tells you why (see table below)
      status.textContent = `Couldn't open: ${err.code}`;
    }
  </script>
</body>
```

`sdk.proxy.openMount(name)` returns a `ProxyMountSession`:

| Field | Use |
| --- | --- |
| `iframeUrl` | Set as the panel iframe `src`. The proxy-session cookie is already minted. |
| `openUrl` | Wire to an "Open in browser" link/`target="_blank"`. Navigating top-level re-mints the cookie first-party — **required where framed third-party cookies are blocked (Safari/WebKit)**, harmless elsewhere. |

Always render the `openUrl` affordance. It's the only path that works when the
framed cookie is blocked.

### Option B — host-owned surface with `reserveMount`

The **shell** renders the proxied app — a hardened `<webview>` on desktop, a
sandboxed `<iframe>` on web — over a placeholder element you reserve. Your panel
never sets a `src`; it lays out a box and hands it to the SDK.

```html
<!-- frontend/index.html -->
<body>
  <!-- The shell paints the proxied app over this element's rect. Give it a real
       size (here it fills the panel); the SDK reports its layout to the shell. -->
  <div id="mount" style="position:absolute; inset:0;"></div>

  <!-- Served by the runtime; do not bundle it yourself. -->
  <script src="/sdk/plugin-frontend.js"></script>
  <script type="module">
    const MOUNT = "demo"; // must equal a proxy_mounts[].name

    const sdk = await window.UncodedPlugin.createPluginFrontend();
    const el = document.getElementById("mount");

    // The shell bootstraps the session and positions the surface over `el`.
    // Returns an idempotent dispose fn that releases the viewport.
    const release = sdk.proxy.reserveMount(MOUNT, el);

    // Optional: release on teardown. The shell also cleans up when the iframe is
    // destroyed, so this is belt-and-suspenders.
    window.addEventListener("pagehide", () => release(), { once: true });
  </script>
</body>
```

`reserveMount(name, el)` is **synchronous** and returns an idempotent dispose
function — there's no session object to read, because the shell owns the surface.
Pass a non-empty mount name (it throws `ProxyError("INVALID_ARGUMENT")` otherwise);
all other failures (bootstrap, not-approved, framing) surface in the shell-owned
UI, not as a throw here. What the shell does for you, by platform:

| | Desktop (Electron) | Web (browser) |
| --- | --- | --- |
| Surface | dedicated hardened `<webview>` | host-owned sandboxed `<iframe>` |
| Framing-hostile upstream | loads — a webview isn't bound by `X-Frame-Options`/`frame-ancestors` | can't be framed → shows an **Open in browser** prompt |
| Session isolation | own per-server partition (`persist:proxy:<serverId>`), separate cookie jar from the in-app browser | the browser's normal cookie rules; bootstrap uses the first-party path |
| Camera / mic / location / notifications / MIDI | **native allow/deny dialog**, remembered per mount | the browser's own prompt, subject to the iframe `allow` policy |
| Off-mount navigation | links to other origins open in the **system browser**, not in-surface | normal sandboxed-iframe behavior |
| Bootstrap URL | the first-party `openUrl` ticket, so the cookie lands inside the webview partition | the in-place `url`; the bootstrap `Set-Cookie` authorizes it |

You don't choose webview-vs-iframe — the shell picks based on whether it's running
in the desktop app. The dispose function is the only thing you manage.

> The mount name and the placeholder element are the **only** things your plugin
> supplies. The shell derives the server, plugin slug, and tunnel origin from the
> trusted panel context — never from the iframe's messages — and owns the
> surface's positioning, lifecycle, and teardown.

### `ProxyError`

`openMount()` throws a `ProxyError` with a `.code` (and `.status`):

| `code` | Meaning |
| --- | --- |
| `INVALID_ARGUMENT` | Bad mount name passed to `openMount()`. |
| `UNAUTHORIZED` | 401 — missing/expired session token. |
| `FORBIDDEN` | 403 — owner-only mount, capability missing. |
| `NOT_FOUND` | 404 — plugin/mount not declared. |
| `NOT_APPROVED` | 409 — **mount not approved by the server admin** (the common one during setup). |
| `RATE_LIMITED` | 429. |
| `NETWORK_ERROR` | fetch rejected (offline / CORS / DNS). |
| `MALFORMED_RESPONSE` | 2xx body missing `url`/`openUrl`. |
| `BOOTSTRAP_FAILED` | any other non-2xx. |

***

## 4. Install & run (local testing)

Dropping a plugin folder is **not** enough. Three things must be true, in order.

### a. Place the folder

Install under the server's plugin directory, named exactly the manifest `name`:

```
<server-data>/plugins/<slug>/
# e.g. C:\Users\you\.uncorded\servers\<server>\plugins\proxy-demo\
#   manifest.json
#   backend/index.ts        (+ node_modules if it imports the SDK)
#   frontend/index.html
```

### b. Register the slug in `server.json`

The runtime only loads plugins listed in `installed_plugins`. Add the slug to
the server's `server.json` (the runtime reads it at boot — see
[`runtime/src/main.ts`](https://github.com/UnCorded/uncorded-platform/blob/main/runtime/src/main.ts)):

```json
{
  "installed_plugins": ["proxy-demo"]
}
```

### c. Restart through the desktop app — **not** `docker restart`

The runtime reads `installed_plugins` only at boot, so the container must be
recreated to pick up the change. **Restart via the desktop app / orchestrator**,
which tears down and recreates the container.

> ⚠️ **Never `docker restart` a server using an authenticated Cloudflare
> tunnel.** The tunnel token lives at `/run/tunnel/tunnel.json` on a **tmpfs**
> mount and is piped in over stdin when the desktop app *creates* the container.
> A bare `docker restart` does not re-pipe it, so the tunnel silently degrades.
> The container's restart policy is `no` by design — the desktop app owns the
> lifecycle and rebuilds the container (re-piping the token) on launch. Always
> go through desktop.

### Reaching a host app from the Docker runtime

The runtime container uses **bridge networking**, so `localhost` inside the
container is the container, not your machine. To proxy an app running on your
host, set the upstream setting to:

```
http://host.docker.internal:<port>
```

(`host.docker.internal` is a Docker Desktop feature; it resolves to the host.)

***

## 5. Making the proxied app load correctly

A mount is served at the **subpath** `/proxy/<slug>/<mount>/`, not at the root.
Most "the panel is blank" problems are an app that assumes it lives at `/`.

### The mount is a subpath — give your app its base path

The runtime rewrites **root-absolute URLs in HTML and CSS** (`/styles/app.css` →
`/proxy/<slug>/<mount>/styles/app.css`) — including those in inline
`style="…url()…"` and `<base href>` — so a static page loads. It does **not**
rewrite URLs your app builds in **JavaScript** (`fetch("/api/…")`, dynamic
`import()`, a WebSocket/`socket.io` connection URL), nor absolute URLs that
hard-code the upstream's own host. Those still miss the mount.

So your app needs to know its public base path. The runtime tells it on every
upstream request (HTTP and WebSocket) via:

```
X-Forwarded-Prefix: /proxy/<slug>/<mount>
```

If your framework is reverse-proxy-aware it reads that header and emits URLs under
the mount automatically — nothing to do. Otherwise set the app's own base-path
option to that exact path:

| App / framework | Base-path setting |
| --- | --- |
| Foundry VTT | `routePrefix` (Configuration → or `options.json`) |
| Vite (dev) | `--base /proxy/<slug>/<mount>/` (plus `--host`, see below) |
| Vite / Rollup (build) | `base` in `vite.config` |
| Next.js | `basePath` in `next.config.js` |
| Create React App | `"homepage"` in `package.json` (or `PUBLIC_URL`) |
| Express / Node | mount the router under the prefix, or read `X-Forwarded-Prefix` |
| Generic | a "base path" / "base href" / "script name" / "context path" setting |

> **Caveat — the prefix has three path segments** (`proxy`, `<slug>`, `<mount>`).
> A few apps only accept a single-segment route prefix; those can't be mounted at
> a subpath and need to be run at a dedicated origin instead.

### Authentication — cookies *or* tokens both work

The proxy is auth-agnostic. Whatever your app uses to authenticate its own users
flows through untouched:

* **Session cookies** — your app's `Set-Cookie` is rewritten to the mount path and
  replayed by the browser on every request, including the WebSocket handshake.
* **Bearer / token-in-`localStorage`** — your app's own `Authorization: Bearer …`
  header is forwarded to its backend.

UnCorded's *own* session never reaches your app: the proxy-session cookie and the
bootstrap Bearer are stripped, and the authenticated user is passed separately as
`X-Uncorded-User-Id`.

### What your app receives

Every forwarded request (HTTP and WS) carries:

| Header | Value |
| --- | --- |
| `Host` | the upstream's own host — generate absolute URLs from `X-Forwarded-Host` instead if your app emits any |
| `X-Forwarded-Host` | the public UnCorded host the user addressed |
| `X-Forwarded-Proto` | `https` / `http` |
| `X-Forwarded-For` | client IP |
| `X-Forwarded-Prefix` | `/proxy/<slug>/<mount>` — your public base path |
| `X-Uncorded-User-Id` | the authenticated UnCorded user |

Responses stream through as-is. The runtime requests **uncompressed** bodies from
your app (`Accept-Encoding: identity`) so it can rewrite HTML/CSS reliably — you
configure nothing, and the public edge still compresses to the end user.

### Real-time apps (WebSockets)

Declare `proxy.websocket:self` in `permissions`. The proxy then bridges
`wss://…/proxy/<slug>/<mount>/*` to the upstream and — **on the handshake** —
forwards the same context it sends on HTTP: your app's cookies (so a socket
authenticated by session cookie, like Foundry's, sees its session), any
`Authorization` header, the `x-forwarded-*` identity headers, and
`X-Forwarded-Prefix`. You don't configure any of this; it mirrors the HTTP path
automatically.

> **Token auth over WebSockets:** browsers can't set an `Authorization` header on
> a `WebSocket()` — so token-auth realtime apps pass the token in the connection
> URL's query string or a `Sec-WebSocket-Protocol` subprotocol. Both pass through
> the proxy untouched. (The forwarded `Authorization` above covers non-browser ws
> clients and server-to-server sockets.)

> **Origin checks:** the runtime composes the upstream socket itself, so a WS
> server that enforces a strict `Origin` allowlist (some `socket.io` configs,
> Jupyter) may need the upstream's own origin allowed. Most apps authenticate the
> socket by cookie/token and don't require this.

**Frame size — fixing `1009` closes.** Each WebSocket frame is relayed whole (a
frame can't be streamed), and the proxy caps it at **64 KiB** by default. A frame
larger than the cap is dropped and the socket closes with code **`1009`** ("message
too big"). Apps that bulk-sync over a socket — Foundry VTT's world/scene sync, live
collaborative editors, anything pushing a large JSON snapshot in one message — hit
this. Raise the cap with `max_frame_bytes` on the mount:

```json
{
  "proxy_mounts": [
    { "name": "foundry", "upstream_setting": "foundry_upstream_url", "max_frame_bytes": 1048576 }
  ]
}
```

It applies in **both directions** and accepts an integer in **`[1024, 16777216]`**
(1 KiB–16 MiB). Set only what you need — the cap also bounds the in-flight buffer,
so an unnecessarily large value raises memory headroom per connection. Changing it
does **not** invalidate the mount approval (it's an operational tuning knob, not an
upstream-identity change). Note this governs socket *frames* only: bulk asset bytes
(map images, scene files, uploads) travel over the **HTTP** path, which streams
without a frame cap — so a huge map doesn't need a huge `max_frame_bytes`, only the
sync *metadata* frame does.

### Changing the upstream or port

* **Editing the upstream setting invalidates the approval** — re-approve after
  changing the URL (see [Approval](#approval-mounts-fail-closed)).
* **Local host apps must bind all interfaces, not loopback.** The runtime runs in
  a container and reaches your machine via `host.docker.internal`. An app bound to
  `127.0.0.1`/`[::1]` refuses that connection (you'll see `PROXY_UPSTREAM_ERROR` /
  502\). Bind `0.0.0.0` (e.g. Vite `--host`) and point the upstream setting at
  `http://host.docker.internal:<port>`.

***

## 6. Approval — mounts fail closed

Proxy mounts are **denied until an owner approves them**. There is no implicit
trust: with no approval row, every request to the mount returns
`PROXY_NOT_APPROVED` (surfaced to the frontend as `NOT_APPROVED` / 409). See
[`runtime/src/http/proxy.ts`](https://github.com/UnCorded/uncorded-platform/blob/main/runtime/src/http/proxy.ts)
and the `proxy_approvals` table.

**To approve:** Server settings → **Plugins** → your plugin → **Settings** →
**Approve** (per mount).

Approval is bound to the upstream value. **Changing the upstream setting
invalidates the approval** — re-approve after editing the URL. (Internally the
approval is keyed and version-bumped so old proxy-session cookies stop working.)

***

## 7. Reference — runtime routes

You won't call these directly (the SDK does), but they're useful when debugging:

| Route | Purpose |
| --- | --- |
| `POST /proxy-sessions/:slug/:mount` | Bootstrap a proxy-session (Bearer auth). Returns `{ url, openUrl }`. This is what `sdk.proxy.openMount()` calls. |
| `/proxy/:slug/:mount/*` | The proxy itself. Validates the session cookie; forwards HTTP + WebSocket to the upstream. |
| `POST /admin/.../plugins/:slug/proxy-mounts/:mount/approve` | Owner/admin approval (driven by the Server settings UI). |

***

## Testing checklist

A quick gate before you say "it works":

* \[ ] Manifest validates: `proxy_mounts[].upstream_setting` references a real
  `string`/`secret` setting; `permissions` include `proxy.http:self`
  (and `proxy.websocket:self` if the app uses sockets).
* \[ ] Plugin folder is under `<server>/plugins/<slug>/` **and** the slug is in
  `server.json` → `installed_plugins`.
* \[ ] If the backend imports `@uncorded/plugin-sdk`, its `node_modules` is
  present in the installed folder.
* \[ ] Restarted via the **desktop app** (not `docker restart`).
* \[ ] Upstream reachable from the container — host apps via
  `http://host.docker.internal:<port>`.
* \[ ] Mount **approved** in Server settings → Plugins → Settings → Approve
  (re-approve if you changed the upstream).
* \[ ] Panel loads: GET `/`, asset requests, and (if used) the WebSocket upgrade
  all reach the upstream.

---

---
url: /examples/text-channels.md
---
# Example: text-channels

`text-channels` is the canonical data-owning plugin — real-time chat with
threads, edits, deletes, file attachments, typing/viewer presence, and a
scheduled file-GC sweep. It exercises nearly every backend capability, so it's
the best single file to read after the guides. This page is an annotated tour;
the full source is
[`plugins/text-channels/backend/index.ts`](https://github.com/UnCorded/uncorded-platform/blob/main/plugins/text-channels/backend/index.ts)
(~1,200 lines).

## The manifest, decoded

```json
{
  "name": "text-channels",
  "type": "core",
  "icon": "Hash",
  "backend":  { "entry": "backend/index.ts" },
  "frontend": { "entry": "frontend/index.html" },
  "permissions": [
    "data.sql:self",
    "events.publish:text-channels.*",
    "events.subscribe:runtime.cascade.*",
    "events.subscribe:runtime.presence.*",
    "events.subscribe:text-channels.*",
    "events.subscribe:core.category.*",
    "broadcast.clients",
    "storage.file:self",
    "runtime.schedule"
  ]
}
```

Every capability traces to a feature below: `data.sql:self` → the channels/messages
DB; `events.publish:text-channels.*` → it announces its own changes;
`events.subscribe:runtime.cascade.*` → it reacts to user deletion;
`events.subscribe:core.category.*` → it nulls soft-FKs when a category is deleted;
`broadcast.clients` → live typing/viewer pushes; `storage.file:self` → attachments;
`runtime.schedule` → the orphan-GC sweep. See
[Permissions → worked example](/reference/permissions#worked-example).

It also declares a `public_schema` (so other plugins can read its `channels` and
`messages` tables), a `sidebar` contribution with `refresh_on` topics, and five
admin `settings` (max message length, edit toggle, attachment limits).

## Startup order: handlers first, async setup last

The single most important structural rule. The file does, top to bottom:

```ts
const plugin = createPlugin();

// 1. Synchronous setup that needs no IPC round-trip.
void refreshSettings();                 // fire-and-forget cache warm
plugin.settings.onChange(() => { /* re-read + push limits to clients */ });

// 2. Register EVERY handler synchronously.
plugin.handle("getChannels", …);
plugin.handle("createChannel", …);
plugin.handle("sendMessage", …);
plugin.handle("sidebar.items", …);
// … etc.

// 3. THEN await the async setup (these are IPC round-trips).
await plugin.permissions.register("text-channels.post", { default_level: 10, … });
await plugin.events.subscribe("runtime.cascade.user.deleted", …);
await plugin.events.subscribe("core.category.deleted", …);
void plugin.schedule.every("attachments.orphan_gc", ORPHAN_GC_INTERVAL_MS, sweepOrphans);
```

Handlers are registered **before** any `await`, so they exist the moment the
runtime starts routing requests. The `await`ed subscriptions/registrations come
after — they're round-trips that may not resolve until the plugin is attached.
See [Lifecycle](/guide/lifecycle#the-ready-handshake).

## Settings: cache at module scope, refresh on change {#settings}

```ts
async function refreshSettings(): Promise<void> {
  const values = await plugin.settings.getAll();
  const len = values["max_message_length"];
  if (typeof len === "number" && len >= 0) maxMessageLength = len; // 0 = "Not Guarded"
  // … allow_edits, attachment limits …
}

void refreshSettings();                       // warm at boot
plugin.settings.onChange(() => {
  void refreshSettings().then(() => {
    plugin.events.publish("text-channels.attachments.settings_updated", { … });
  });
});
```

Settings are read into module-scope variables once and refreshed when an admin
saves. Note `0` is a meaningful stored value ("unlimited"), so the guard is
`len >= 0`, not `if (len)`. After a change it re-publishes the new attachment
limits so open client trays update without a reload.

## A handler end-to-end: `sendMessage`

```ts
plugin.handle("sendMessage", async (params, user) => {
  // 1. Permission gate — application logic, not a manifest capability.
  if (!(await plugin.permissions.check(user.id, "text-channels.post"))) {
    throw new Error("Permission denied: text-channels.post");
  }

  // 2. Validate every client-supplied param. Never trust params.
  const channelId = params["channel_id"];
  const content = params["content"];
  if (typeof channelId !== "string") throw new Error("channel_id is required");
  if (typeof content !== "string")   throw new Error("content is required");
  if (maxMessageLength > 0 && content.length > maxMessageLength) {
    throw new Error("MESSAGE_TOO_LONG");
  }

  // 3. Validate attachments against the runtime's on-disk view BEFORE the write,
  //    so a row never references a missing file.
  const attachments = await validateAttachments(params["attachments"]);
  if (content.length === 0 && attachments.length === 0) throw new Error("EMPTY_MESSAGE");

  // 4. Write. Replies bump the parent's counters atomically via db.batch().
  const id = crypto.randomUUID();
  await plugin.db.batch([
    { sql: "INSERT INTO messages (...) VALUES (...)", params: [...] },
    { sql: "UPDATE messages SET reply_count = reply_count + 1, last_reply_at = ? WHERE id = ?", params: [now, parentId] },
  ]);

  // 5. Enrich (join author profiles from core, sign attachment URLs), then
  //    publish to the event bus and return to the caller.
  const enriched = enrichMessage(message, memberMap, wireAttachments);
  plugin.events.publish("text-channels.message.created", enriched);
  return enriched;
});
```

The shape — **gate → validate → write → publish → return** — repeats across
`createChannel`, `editMessage`, `deleteMessage`. Two role checks appear:
`permissions.check(user.id, "text-channels.post")` for posting, and
`permissions.hasMinLevel(user.id, 60)` for moderator-only actions like creating
or deleting a channel.

## The `sidebar.items` reserved handler

The shell calls this to build the sidebar. It returns items (plus optional
admin actions), shaped by the caller's role:

```ts
plugin.handle("sidebar.items", async (_params, user) => {
  const channels = await plugin.db.query(`SELECT … FROM channels ORDER BY position ASC`);
  const isMod = await plugin.permissions.hasMinLevel(user.id, 60);

  const items = channels.map((c) => ({
    id: c.id, label: c.name, icon: "hash",
    panelType: "plugin", slug: "text-channels", section: "Chat",
    group_id: c.category_id,
    ...(isMod ? { adminActions: [ { id: "edit-channel", … }, { id: "delete-channel", … } ] } : {}),
  }));

  return isMod
    ? { items, adminActions: [{ id: "create-channel", label: "New Channel", icon: "plus" }] }
    : { items };
});
```

The manifest's `sidebar.refresh_on` lists the topics
(`text-channels.channel.created`, `…updated`, `…deleted`) that make the shell
re-call this handler — which is why creating a channel makes the sidebar update
live.

## Presence: typing & viewer counts

Presence is **scoped, ephemeral, and request-context-bound**. The `setTyping` /
`setViewingChannel` handlers `join`/`leave` a scope; a `watch` per channel pushes
the live set to the right audience via `broadcast.toUsers`:

```ts
plugin.handle("setTyping", async (params, user) => {
  if (typing) await plugin.presence.join(scope, user.id, { typing_until: Date.now() + … });
  else        await plugin.presence.leave(scope, user.id);
});

// One watcher per channel, registered at startup and on channel.created:
await plugin.presence.watch(scope, (entries) => broadcastTypingTo(viewersScope, scope, entries), { coalesceMs: 50 });
```

`join`/`leave` must run inside a request handler — they infer the WS session from
[request context](/reference/backend-sdk#request-context). The handlers also
`requireChannel(channelId)` first: presence accepts arbitrary client ids, and
without an existence check a client could spam random UUIDs to grow the watcher
registry unboundedly.

## Reacting to the runtime: cascade & soft-FK cleanup

Two subscriptions keep the plugin's data consistent with the rest of the server:

```ts
// A user was deleted anywhere → anonymize their messages.
// NOTE: runtime.cascade.user.deleted is a reserved topic — wired here ahead of
// the runtime emitting it (pending Central account-deletion). The handler is
// registered correctly but won't fire until that delta ships. See
// [Data & events → runtime events](/guide/data-and-events#runtime-published-events-you-can-subscribe-to).
await plugin.events.subscribe("runtime.cascade.user.deleted", async (event) => {
  const userId = (event.payload as { user_id?: string }).user_id;
  if (typeof userId === "string") {
    await plugin.db.run(
      "UPDATE messages SET content='[deleted]', author_id='[deleted]', attachments=NULL WHERE author_id = ?",
      [userId],
    );
  }
});

// An admin deleted a category → NULL the soft foreign key (channels fall back to "Uncategorized").
await plugin.events.subscribe("core.category.deleted", async (event) => {
  const id = (event.payload as { id?: string }).id;
  if (id) await plugin.db.run("UPDATE channels SET category_id = NULL WHERE category_id = ?", [id]);
});
```

Categories are referenced by id as a **soft FK** — there's no cross-plugin
foreign key, so the plugin listens for the delete and cleans up itself. This is
the standard pattern for referencing [core](/reference/backend-sdk#core)
categories.

## Files + the scheduled orphan sweep

Clients upload attachments straight to the runtime; the backend validates them at
`sendMessage` and stores only the filename + metadata in the row (URLs are signed
fresh per read). Files whose message is deleted become orphans, reclaimed by an
hourly schedule:

```ts
async function sweepOrphans() {
  const onDisk = await plugin.files.list();
  const referenced = await buildReferencedFilenames();   // scan messages.attachments
  for (const f of onDisk) {
    if (referenced.has(f.filename)) continue;
    if (Date.now() - f.mtime < ORPHAN_GRACE_MS) continue; // grace window for in-flight uploads
    await plugin.files.delete(f.filename);
  }
}

void plugin.schedule.every("attachments.orphan_gc", ORPHAN_GC_INTERVAL_MS, sweepOrphans);
void sweepOrphans();   // also run once at boot
```

Re-registering the same schedule name replaces the previous timer (idempotent
across reloads). The grace window prevents race-deleting a file a user just
uploaded but hasn't attached yet.

## Migrations

Schema is built by the SQL files in `migrations/`, applied in filename order
before the plugin spawns. `001_create_tables.sql` creates the tables and seeds a
default channel; later files (`002_add_threads.sql`, `003_add_category_id.sql`,
`004_attachments.sql`) add columns as the plugin grew — **append a new file,
never edit an applied one**:

```sql
CREATE TABLE channels (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  topic TEXT DEFAULT '',
  created_at INTEGER NOT NULL
);
CREATE TABLE messages (
  id TEXT PRIMARY KEY,
  channel_id TEXT NOT NULL REFERENCES channels(id),
  author_id TEXT NOT NULL,
  content TEXT NOT NULL,
  created_at INTEGER NOT NULL,
  edited_at INTEGER
);
CREATE INDEX idx_messages_channel_time ON messages(channel_id, created_at);

INSERT INTO channels (id, name, topic, created_at)
VALUES ('00000000-0000-0000-0000-000000000001', 'general', 'General discussion', strftime('%s','now') * 1000);
```

## What to copy

* The **startup order** (handlers sync, subscriptions/schedule awaited after).
* The **gate → validate → write → publish → return** handler shape.
* Caching settings at module scope + `onChange`.
* Existence-checking any client-supplied id before using it.
* Append-only migrations.

From here: the [getting-started guide](/guide/getting-started) builds a smaller
plugin from scratch, and the [backend SDK reference](/reference/backend-sdk)
documents every method these handlers call.