@owncast/plugin-sdk 0.6.0 → 0.11.0

package/index.js

@@ -1,22 +1,21 @@
 // @owncast/plugin-sdk runtime, bundled into every plugin.
 //
 // Authors define typed handlers (onChatMessage, filterChatMessage, ...) plus
-// an `on: { [customEvent]: handler }` object for plugin-emitted events. The
+// an `on: { [localCustomHook]: handler }` object for plugin-owned events. The
 // SDK derives the manifest's subscriptions from which handlers are present
-// and returns them via register(); authors don't maintain a duplicate list.
+// and returns them via register(). The host qualifies custom hooks with the
+// declaring plugin's slug.
 
 let registered = null;
 
-// Command metadata recorded by defineCommands, reported to the host via
-// register() so it can build a unified `!help` across all plugins. One entry
-// per command: { name, prefix, description, usage, aliases, modOnly }.
+// Command registrations used for matching, dispatch, and the unified `!help`.
 const commandManifest = [];
 
 // Host-driven timers. The sandbox has no setTimeout, so owncast.timer.* asks
 // the host to schedule a callback and call back via the internal "timer.fire"
 // event. The author's callback stays here in the long-lived instance, keyed by
 // a guest-allocated id the host echoes back. State persists across calls
-// because the plugin instance is reused; timers are dropped on reload.
+// because the plugin instance is reused. Timers are dropped on reload.
 let nextTimerId = 1;
 const timerCallbacks = new Map(); // id -> { fn, repeat }
 
@@ -43,13 +42,22 @@ const Events = Object.freeze({
   // Once-a-second tick for periodic work (opt in by defining onTick)
   Tick: "tick",
   // Fediverse, engagement (metadata only) + inbound posts (with content)
+  FediverseActivity: "fediverse.activity",
   FediverseFollow: "fediverse.follow",
   FediverseLike: "fediverse.like",
   FediverseRepost: "fediverse.repost",
+  FediverseQuote: "fediverse.quote",
   FediverseMention: "fediverse.mention",
   FediverseReply: "fediverse.reply",
 });
 
+const InternalEvents = Object.freeze({
+  ChatCommand: "chat.command",
+  TimerFire: "timer.fire",
+});
+
+const DefaultCommandPrefix = "!";
+
 const Permissions = Object.freeze({
   ChatSend: "chat.send",
   ChatHistory: "chat.history",
@@ -58,6 +66,7 @@ const Permissions = Object.freeze({
   StorageKV: "storage.kv",
   StorageUpload: "storage.upload",
   StorageFS: "storage.fs",
+  StorageSQL: "storage.sql",
   EventsEmit: "events.emit",
   NetworkFetch: "network.fetch",
   HttpServe: "http.serve",
@@ -65,7 +74,10 @@ const Permissions = Object.freeze({
   NotificationsSend: "notifications.send",
   UsersRead: "users.read",
   UsersModerate: "users.moderate",
+  UsersRegister: "users.register",
+  AuthGate: "auth.gate",
   FediversePost: "fediverse.post",
+  FediverseInbound: "fediverse.inbound",
   HttpSSE: "http.sse",
   VideoConfigRead: "videoconfig.read",
   VideoConfigWrite: "videoconfig.write",
@@ -84,6 +96,30 @@ const filter = Object.freeze({
   },
 });
 
+// Verdict helpers for onAuthCheck (the optional re-validation hook the host runs
+// on a viewer's page load). `ok` keeps the session, `refresh` keeps it and
+// extends the cookie (optional `ttl` seconds), and `deny` ends it and bounces
+// the viewer back to the login screen.
+const authCheck = Object.freeze({
+  ok() {
+    return { action: "ok" };
+  },
+  refresh(opts) {
+    return { action: "refresh", ...(opts || {}) };
+  },
+  deny(reason) {
+    return { action: "deny", reason: reason || "" };
+  },
+});
+
+// dispatchAuthCheck routes the host's re-validation call to the author's
+// onAuthCheck handler. No handler → always "ok" (the hook is optional, and a
+// plugin that doesn't implement it simply never revokes mid-session).
+function dispatchAuthCheck(req) {
+  if (!registered || !isFn(registered.onAuthCheck)) return { action: "ok" };
+  return registered.onAuthCheck(req) || { action: "ok" };
+}
+
 // Distinguishes notification handlers from filter handlers in the HANDLERS
 // map below. Internal, not part of the public API.
 const HandlerKind = Object.freeze({
@@ -126,6 +162,11 @@ const HANDLERS = Object.freeze({
   onSseDisconnect: { event: Events.SseDisconnect, kind: HandlerKind.Notify },
   // Once-a-second tick
   onTick: { event: Events.Tick, kind: HandlerKind.Notify },
+  // Verified inbound ActivityPub activity (raw JSON object)
+  onFediverse: {
+    event: Events.FediverseActivity,
+    kind: HandlerKind.Notify,
+  },
   // Fediverse engagement (actor + target metadata)
   onFediverseFollow: {
     event: Events.FediverseFollow,
@@ -136,6 +177,10 @@ const HANDLERS = Object.freeze({
     event: Events.FediverseRepost,
     kind: HandlerKind.Notify,
   },
+  onFediverseQuote: {
+    event: Events.FediverseQuote,
+    kind: HandlerKind.Notify,
+  },
   // Fediverse inbound posts (with content)
   onFediverseMention: {
     event: Events.FediverseMention,
@@ -144,156 +189,70 @@ const HANDLERS = Object.freeze({
   onFediverseReply: { event: Events.FediverseReply, kind: HandlerKind.Notify },
 });
 
-// typeof comparisons in well-known categories. JS guarantees these strings,
-// but we go through named constants so a stray typo can't pass silently.
-const JsType = Object.freeze({
-  Function: "function",
-  Object: "object",
-});
-const isFn = (x) => typeof x === JsType.Function;
-const isObj = (x) => x !== null && typeof x === JsType.Object;
+const isFn = (x) => typeof x === "function";
+const isObj = (x) => x !== null && typeof x === "object";
 
 function definePlugin(def) {
-  // `commands` is declarative sugar: give definePlugin a command table (and an
-  // optional commandPrefix) and the SDK wires the chat subscription for you —
-  // no onChatMessage needed. It expands into an onChatMessage handler here, so
-  // subscription derivation and dispatch treat it like any chat handler. If you
-  // also pass onChatMessage, the command router runs first, then your handler.
-  // For advanced composition (e.g. dropping command messages from chat via a
-  // filter), use the lower-level defineCommands() router directly instead.
-  if (def && isObj(def.commands)) {
-    const router = defineCommands({
-      prefix: def.commandPrefix,
-      caseSensitive: def.commandsCaseSensitive,
-      commands: def.commands,
-      onUnknown: def.onUnknownCommand,
-    });
-    const userHandler = def.onChatMessage;
-    def.onChatMessage = isFn(userHandler)
-      ? (msg) => {
-          router(msg);
-          userHandler(msg);
-        }
-      : router;
-  }
   registered = def;
-  return def;
-}
+  commandManifest.length = 0;
+  if (!def || !isObj(def.commands)) return def;
 
-// defineCommands builds a chat-command router so plugins stop reimplementing
-// prefix parsing, aliases, per-user cooldowns, and moderator gating. It returns
-// a function you feed a ChatMessage (from onChatMessage or filterChatMessage);
-// it parses the command and invokes the matching handler's run(ctx). The return
-// value is true when the message was a command (even if gated), false when it
-// wasn't — so a filter can drop command messages from chat:
-//
-//   const commands = defineCommands({
-//     prefix: "!",
-//     commands: {
-//       uptime: { run: (ctx) => ctx.reply("up!") },
-//       ban: { modOnly: true, cooldownMs: 5000, run: (ctx) => ctx.reply(`bye ${ctx.args[0]}`) },
-//     },
-//   });
-//   module.exports = definePlugin({
-//     onChatMessage: commands,
-//     // or, to hide command messages from chat:
-//     // filterChatMessage: (msg) => (commands(msg) ? filter.drop("command") : filter.pass()),
-//   });
-//
-// run(ctx) receives { msg, user, command, args, argString, reply, replyPrivately }.
-// reply posts publicly; replyPrivately whispers to the sender (falling back to a
-// public post if their connection is unknown). Optional hooks: per-command or
-// top-level onCooldown(ctx) / onDenied(ctx), and a top-level onUnknown(ctx).
-function defineCommands(config) {
-  config = config || {};
-  const prefix = config.prefix || "!";
-  const caseSensitive = !!config.caseSensitive;
-  const norm = (s) => (caseSensitive ? s : s.toLowerCase());
-
-  // Resolve every name and alias to its canonical command definition, and
-  // record metadata so the host can build a unified `!help` (see
-  // describeCommands). Metadata is reported via register(); it never affects
-  // routing.
-  const table = new Map();
-  const defs = config.commands || {};
-  for (const name of Object.keys(defs)) {
-    const def = defs[name];
-    table.set(norm(name), { name, def });
-    for (const alias of def.aliases || []) table.set(norm(alias), { name, def });
+  const prefix =
+    def.commandPrefix == null ? DefaultCommandPrefix : def.commandPrefix;
+  if (typeof prefix !== "string" || prefix.length === 0) {
+    throw new TypeError("commandPrefix must be a non-empty string");
+  }
+  const caseSensitive = !!def.commandsCaseSensitive;
+  for (const name of Object.keys(def.commands)) {
+    const command = def.commands[name];
+    if (!isObj(command)) {
+      throw new TypeError(`command "${name}" must be an object`);
+    }
+    const aliases = command.aliases == null ? [] : command.aliases;
+    if (
+      !Array.isArray(aliases) ||
+      !aliases.every((alias) => typeof alias === "string")
+    ) {
+      throw new TypeError(`command "${name}" aliases must be an array of strings`);
+    }
+    const cooldownMs =
+      command.cooldownMs == null ? 0 : command.cooldownMs;
+    if (!Number.isSafeInteger(cooldownMs) || cooldownMs < 0) {
+      throw new TypeError(`command "${name}" cooldownMs must be a non-negative integer`);
+    }
     commandManifest.push({
       name,
       prefix,
-      description: def.description || "",
-      usage: def.usage || "",
-      aliases: def.aliases || [],
-      modOnly: !!def.modOnly,
+      description: command.description || "",
+      usage: command.usage || "",
+      aliases,
+      modOnly: !!command.modOnly,
+      caseSensitive,
+      cooldownMs,
     });
   }
+  return def;
+}
 
-  // Per-(command,user) cooldown clock, in memory for the plugin's lifetime.
-  const lastRun = new Map();
-
-  return function handle(msg) {
-    const body = (msg && msg.body) || "";
-    if (!body.startsWith(prefix)) return false;
-    const rest = body.slice(prefix.length);
-    const parts = rest.split(/\s+/).filter(Boolean);
-    if (parts.length === 0) return false;
-    const called = parts[0];
-    const args = parts.slice(1);
-    const argString = rest.slice(called.length).trim();
-
-    const ctx = {
-      msg,
-      user: msg && msg.user,
-      command: norm(called),
-      args,
-      argString,
-      reply: (text) => owncast.chat.send(text),
-      replyPrivately: (text) => {
-        if (!owncast.chat.replyTo(msg, text)) owncast.chat.send(text);
-      },
-    };
-
-    const entry = table.get(norm(called));
-    if (!entry) {
-      if (isFn(config.onUnknown)) config.onUnknown(ctx);
-      return false;
-    }
-    const { name, def } = entry;
-    ctx.command = name;
-
-    // Moderator gating: the sender's scopes must include MODERATOR.
-    if (def.modOnly) {
-      const scopes = (msg.user && msg.user.scopes) || [];
-      if (!scopes.includes("MODERATOR")) {
-        if (isFn(def.onDenied)) def.onDenied(ctx);
-        else if (isFn(config.onDenied)) config.onDenied(ctx);
-        return true; // matched a command, but the caller wasn't allowed
-      }
-    }
-
-    // Per-user cooldown, clocked off msg.timestamp so it's deterministic in
-    // tests and independent of any sandbox clock quirks.
-    const cooldownMs = def.cooldownMs || 0;
-    if (cooldownMs > 0) {
-      const userId =
-        (msg.user && msg.user.id) ||
-        (msg.clientId != null ? `c${msg.clientId}` : "anon");
-      const key = `${name}${userId}`;
-      const now = msg.timestamp ? new Date(msg.timestamp).getTime() : 0;
-      const prev = lastRun.get(key);
-      if (now && prev && now - prev < cooldownMs) {
-        if (isFn(def.onCooldown)) def.onCooldown(ctx);
-        else if (isFn(config.onCooldown)) config.onCooldown(ctx);
-        return true;
-      }
-      if (now) lastRun.set(key, now);
-    }
+function dispatchCommand(event) {
+  if (!isObj(event)) return;
+  if (!registered || !isObj(registered.commands)) return;
+  const command = registered.commands[event.command];
+  if (!command || !isFn(command.run)) return;
 
-    if (isFn(def.run)) def.run(ctx);
-    return true;
-  };
+  const msg = event.message;
+  command.run({
+    msg,
+    user: msg && msg.user,
+    command: event.command,
+    invokedAs: event.invokedAs || event.command,
+    args: event.args || [],
+    argString: event.argString || "",
+    reply: (text) => owncast.chat.send(text),
+    replyPrivately: (text) => {
+      if (!owncast.chat.replyTo(msg, text)) owncast.chat.send(text);
+    },
+  });
 }
 
 // Used by the build-generated entry to compute subscriptions for register().
@@ -324,9 +283,8 @@ function describeSubscriptions() {
   return { notify, filter: filterSubs };
 }
 
-// Used by the build-generated entry to report the plugin's chat commands in
-// register(), so the host can answer a unified `!help`. Empty when the plugin
-// declares no commands.
+// Used by the build-generated entry to report command registrations to the
+// host for matching, dispatch, and the unified `!help`.
 function describeCommands() {
   return commandManifest;
 }
@@ -336,7 +294,7 @@ function dispatchEvent(envelope) {
   // Internal: a host-scheduled timer elapsed. Run the author's callback,
   // dropping one-shot entries first so a throw still cleans up. Not routed to
   // user handlers or the `on` map.
-  if (eventType === "timer.fire") {
+  if (eventType === InternalEvents.TimerFire) {
     const id = payload && payload.id;
     const entry = timerCallbacks.get(id);
     if (entry) {
@@ -345,6 +303,10 @@ function dispatchEvent(envelope) {
     }
     return;
   }
+  if (eventType === InternalEvents.ChatCommand) {
+    dispatchCommand(payload);
+    return;
+  }
   if (!registered) return;
   for (const [method, info] of Object.entries(HANDLERS)) {
     if (
@@ -391,16 +353,6 @@ function dispatchHttp(request) {
   };
 }
 
-// permError builds an actionable Error and logs it to stderr (which the
-// host runtime captures), so a plugin author running `owncast-plugin
-// serve` or hitting the host's logs sees exactly which permission to
-// add to their manifest. apiName is the SDK call the author wrote
-// (e.g. "owncast.actions.set"); perm is the manifest permission string.
-function permError(apiName, perm) {
-  const msg = `${apiName} requires the '${perm}' permission. Add it to your plugin.manifest.json's "permissions" array.`;
-  console.error(`[owncast-plugin] ${msg}`);
-  return new Error(msg);
-}
 
 // scheduleTimer registers a callback and asks the host to schedule it. The id
 // is guest-allocated and echoed back on "timer.fire". Throws if the host
@@ -423,50 +375,110 @@ function scheduleTimer(fn, ms, repeat) {
   return id;
 }
 
+// hostFns returns the complete host import table. Missing imports indicate an
+// incompatible host. Permission denials are reported by result-returning calls.
+function hostFns(name, perm) {
+  const fns = Host.getFunctions();
+  if (!fns[name]) throw new Error(`permission '${perm}' not granted`);
+  return fns;
+}
+
+function operationResult(offset, failureMessage) {
+  if (offset == 0) return { error: failureMessage };
+  try {
+    const result = JSON.parse(Memory.find(offset).readString());
+    if (result === null || typeof result !== "object" || Array.isArray(result)) {
+      return { error: failureMessage };
+    }
+    return result;
+  } catch {
+    return { error: failureMessage };
+  }
+}
+
+function requireOperationResult(offset, failureMessage) {
+  const result = operationResult(offset, failureMessage);
+  if (Object.prototype.hasOwnProperty.call(result, "error")) {
+    throw new Error(result.error || failureMessage);
+  }
+  return result;
+}
+
+function sqlResult(offset) {
+  return requireOperationResult(offset, "SQL host call failed");
+}
+
+function sqlRows(result) {
+  if (!Array.isArray(result.columns) || !Array.isArray(result.rows)) {
+    throw new Error("SQL host returned an invalid result");
+  }
+  return result.rows.map((values) => {
+    if (!Array.isArray(values)) {
+      throw new Error("SQL host returned an invalid result");
+    }
+    return Object.fromEntries(result.columns.map((column, i) => [column, values[i]]));
+  });
+}
+
+function sqlQuery(sql, params, maxRows) {
+  const fns = hostFns("owncast_sql_query", Permissions.StorageSQL);
+  const payload = { sql: String(sql), params: Array.from(params || []) };
+  if (maxRows) payload.maxRows = maxRows;
+  const request = Memory.fromString(JSON.stringify(payload));
+  return sqlResult(fns.owncast_sql_query(request.offset));
+}
+
+function logToHost(name, message) {
+  const fn = Host.getFunctions()[name];
+  if (!fn) throw new Error("owncast.log is unavailable in this host");
+  fn(Memory.fromString(String(message)).offset);
+}
+
 const owncast = {
+  log: {
+    info(message) {
+      logToHost("owncast_log_info", message);
+    },
+    warning(message) {
+      logToHost("owncast_log_warning", message);
+    },
+    error(message) {
+      logToHost("owncast_log_error", message);
+    },
+  },
   chat: {
     send(text) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_send_chat)
-        throw new Error(`permission '${Permissions.ChatSend}' not granted`);
+      const fns = hostFns("owncast_send_chat", Permissions.ChatSend);
       fns.owncast_send_chat(Memory.fromString(text).offset);
     },
     sendAction(text) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_send_chat_action)
-        throw new Error(`permission '${Permissions.ChatSend}' not granted`);
+      const fns = hostFns("owncast_send_chat_action", Permissions.ChatSend);
       fns.owncast_send_chat_action(Memory.fromString(text).offset);
     },
     system(body) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_send_chat_system)
-        throw new Error(`permission '${Permissions.ChatSend}' not granted`);
+      const fns = hostFns("owncast_send_chat_system", Permissions.ChatSend);
       fns.owncast_send_chat_system(Memory.fromString(body).offset);
     },
     history(limit) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_chat_history)
-        throw new Error(`permission '${Permissions.ChatHistory}' not granted`);
+      const fns = hostFns("owncast_chat_history", Permissions.ChatHistory);
       const offset = fns.owncast_chat_history(limit || 0);
       if (offset == 0) return [];
       return JSON.parse(Memory.find(offset).readString());
     },
     deleteMessage(messageId) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_delete_message)
-        throw new Error(`permission '${Permissions.ChatModerate}' not granted`);
-      fns.owncast_delete_message(Memory.fromString(String(messageId)).offset);
+      const fns = hostFns("owncast_delete_message", Permissions.ChatModerate);
+      const offset = fns.owncast_delete_message(
+        Memory.fromString(String(messageId)).offset,
+      );
+      requireOperationResult(offset, "chat.deleteMessage failed");
     },
     kick(clientId) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_kick_client)
-        throw new Error(`permission '${Permissions.ChatModerate}' not granted`);
-      fns.owncast_kick_client(BigInt(clientId));
+      const fns = hostFns("owncast_kick_client", Permissions.ChatModerate);
+      const offset = fns.owncast_kick_client(BigInt(clientId));
+      requireOperationResult(offset, "chat.kick failed");
     },
     sendTo(clientId, text) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_send_chat_to)
-        throw new Error(`permission '${Permissions.ChatSend}' not granted`);
+      const fns = hostFns("owncast_send_chat_to", Permissions.ChatSend);
       fns.owncast_send_chat_to(
         BigInt(clientId),
         Memory.fromString(text).offset,
@@ -487,9 +499,7 @@ const owncast = {
       return true;
     },
     clients() {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_chat_clients)
-        throw new Error(`permission '${Permissions.ChatHistory}' not granted`);
+      const fns = hostFns("owncast_chat_clients", Permissions.ChatHistory);
       const offset = fns.owncast_chat_clients();
       if (offset == 0) return [];
       return JSON.parse(Memory.find(offset).readString());
@@ -497,49 +507,79 @@ const owncast = {
   },
   users: {
     list() {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_users_list)
-        throw new Error(`permission '${Permissions.UsersRead}' not granted`);
+      const fns = hostFns("owncast_users_list", Permissions.UsersRead);
       const offset = fns.owncast_users_list();
       if (offset == 0) return [];
       return JSON.parse(Memory.find(offset).readString());
     },
     get(id) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_user_get)
-        throw new Error(`permission '${Permissions.UsersRead}' not granted`);
+      const fns = hostFns("owncast_user_get", Permissions.UsersRead);
       const offset = fns.owncast_user_get(Memory.fromString(id).offset);
       if (offset == 0) return null;
       return JSON.parse(Memory.find(offset).readString());
     },
     setEnabled(id, enabled, reason) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_user_set_enabled)
-        throw new Error(
-          `permission '${Permissions.UsersModerate}' not granted`,
-        );
-      fns.owncast_user_set_enabled(
+      const fns = hostFns("owncast_user_set_enabled", Permissions.UsersModerate);
+      const offset = fns.owncast_user_set_enabled(
         Memory.fromString(id).offset,
         enabled ? 1 : 0,
         Memory.fromString(reason || "").offset,
       );
+      requireOperationResult(offset, "users.setEnabled failed");
     },
     banIP(ip) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_ban_ip)
-        throw new Error(
-          `permission '${Permissions.UsersModerate}' not granted`,
-        );
-      fns.owncast_ban_ip(Memory.fromString(ip).offset);
+      const fns = hostFns("owncast_ban_ip", Permissions.UsersModerate);
+      const offset = fns.owncast_ban_ip(Memory.fromString(ip).offset);
+      requireOperationResult(offset, "users.banIP failed");
+    },
+    // Find or create an authenticated Owncast user for an external identity.
+    // profileUrl and handle describe a verified profile. public opts that
+    // identity into public display. Returns { userId }. Throws on host error.
+    // Requires `users.register`.
+    register(opts) {
+      const fns = hostFns("owncast_users_register", Permissions.UsersRegister);
+      const source = typeof opts === "string" ? { authId: opts } : opts || {};
+      const req = {
+        authId: source.authId,
+        displayName: source.displayName,
+        scopes: source.scopes,
+        profileUrl: source.profileUrl,
+        handle: source.handle,
+        public: source.public,
+      };
+      const offset = fns.owncast_users_register(
+        Memory.fromString(JSON.stringify(req)).offset,
+      );
+      return requireOperationResult(offset, "users.register failed"); // { userId }
+    },
+  },
+  // Viewer-authentication gate. Only a plugin holding `auth.gate` (and enabled by
+  // an admin) can issue sessions, and these are valid only inside onHttpRequest,
+  // where the host attaches/clears the signed session cookie on the response.
+  // The admin selects the cumulative, host-owned access mode. Plugins cannot
+  // read or change it.
+  auth: {
+    // Issue a gate session for an already-registered user (see users.register).
+    // `ttl` is optional seconds, and 0/omitted uses the host default. Throws on
+    // host error. Requires `auth.gate`.
+    grantSession(opts) {
+      const fns = hostFns("owncast_auth_grant_session", Permissions.AuthGate);
+      const req = typeof opts === "string" ? { userId: opts } : opts || {};
+      const offset = fns.owncast_auth_grant_session(
+        Memory.fromString(JSON.stringify(req)).offset,
+      );
+      requireOperationResult(offset, "auth.grantSession failed");
+    },
+    // Clear the current viewer's gate session (logout). The plugin still owns the
+    // response/redirect. Requires `auth.gate`.
+    endSession() {
+      const fns = hostFns("owncast_auth_end_session", Permissions.AuthGate);
+      fns.owncast_auth_end_session();
     },
   },
   storage: {
     upload(name, data) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_storage_upload)
-        throw new Error(
-          `permission '${Permissions.StorageUpload}' not granted`,
-        );
+      const fns = hostFns("owncast_storage_upload", Permissions.StorageUpload);
       const dataMem =
         data instanceof Uint8Array
           ? Memory.fromBuffer(
@@ -557,7 +597,7 @@ const owncast = {
       return JSON.parse(Memory.find(offset).readString());
     },
   },
-  // Private, sandboxed filesystem under data/plugin-data/<slug>/. Unlike
+  // Private, sandboxed filesystem under data/plugin-storage/<slug>/files/. Unlike
   // storage.upload (which publishes browser-accessible files), these bytes
   // stay server-side. The host confines every path to this plugin's own
   // directory. All methods require the 'storage.fs' permission.
@@ -565,9 +605,7 @@ const owncast = {
     // Read a file's raw bytes. Returns a Uint8Array, or null if the file
     // doesn't exist (or can't be read).
     read(path) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_fs_read)
-        throw new Error(`permission '${Permissions.StorageFS}' not granted`);
+      const fns = hostFns("owncast_fs_read", Permissions.StorageFS);
       const offset = fns.owncast_fs_read(Memory.fromString(path).offset);
       if (offset == 0) return null;
       return new Uint8Array(Memory.find(offset).readBytes());
@@ -575,19 +613,15 @@ const owncast = {
     // Read a file as UTF-8 text. Returns a string, or null if the file
     // doesn't exist. (The Extism boundary decodes the bytes as UTF-8.)
     readText(path) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_fs_read)
-        throw new Error(`permission '${Permissions.StorageFS}' not granted`);
+      const fns = hostFns("owncast_fs_read", Permissions.StorageFS);
       const offset = fns.owncast_fs_read(Memory.fromString(path).offset);
       if (offset == 0) return null;
       return Memory.find(offset).readString();
     },
     // Write bytes (Uint8Array) or a string to a file, creating parent
-    // directories as needed. Returns { ok, error? }.
+    // directories as needed. Returns { error? }.
     write(path, data) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_fs_write)
-        throw new Error(`permission '${Permissions.StorageFS}' not granted`);
+      const fns = hostFns("owncast_fs_write", Permissions.StorageFS);
       const dataMem =
         data instanceof Uint8Array
           ? Memory.fromBuffer(
@@ -601,46 +635,51 @@ const owncast = {
         Memory.fromString(path).offset,
         dataMem.offset,
       );
-      if (offset == 0) return { ok: false, error: "write failed" };
-      return JSON.parse(Memory.find(offset).readString());
+      return operationResult(offset, "write failed");
     },
     // List the entry names (files and subdirectories) directly inside dir.
     // A missing directory lists as empty. Returns string[].
     list(dir) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_fs_list)
-        throw new Error(`permission '${Permissions.StorageFS}' not granted`);
+      const fns = hostFns("owncast_fs_list", Permissions.StorageFS);
       const offset = fns.owncast_fs_list(Memory.fromString(dir || "").offset);
       if (offset == 0) return [];
       return JSON.parse(Memory.find(offset).readString());
     },
-    // Remove a single file or empty directory. Returns { ok, error? }.
+    // Remove a single file or empty directory. Returns { error? }.
     delete(path) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_fs_delete)
-        throw new Error(`permission '${Permissions.StorageFS}' not granted`);
+      const fns = hostFns("owncast_fs_delete", Permissions.StorageFS);
       const offset = fns.owncast_fs_delete(Memory.fromString(path).offset);
-      if (offset == 0) return { ok: false, error: "delete failed" };
-      return JSON.parse(Memory.find(offset).readString());
+      return operationResult(offset, "delete failed");
     },
     // Report whether a path exists inside the sandbox. Returns boolean.
     exists(path) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_fs_exists)
-        throw new Error(`permission '${Permissions.StorageFS}' not granted`);
+      const fns = hostFns("owncast_fs_exists", Permissions.StorageFS);
       return fns.owncast_fs_exists(Memory.fromString(path).offset) === 1;
     },
   },
+  sql: {
+    exec(sql, params = []) {
+      const fns = hostFns("owncast_sql_exec", Permissions.StorageSQL);
+      const request = Memory.fromString(
+        JSON.stringify({ sql: String(sql), params: Array.from(params || []) }),
+      );
+      return sqlResult(fns.owncast_sql_exec(request.offset));
+    },
+    query(sql, params = []) {
+      return sqlRows(sqlQuery(sql, params));
+    },
+    queryRow(sql, params = []) {
+      // Asking the host for one row keeps a first-row read off the result
+      // budget, so this works against a table `query` would be too big for.
+      return sqlRows(sqlQuery(sql, params, 1))[0] || null;
+    },
+  },
   fediverse: {
     /** Publish a public text-only post to the fediverse on the streamer's
      *  behalf. Returns { url } on success, null on failure (rate-limited,
      *  disabled by admin, etc.). Requires `fediverse.post`. */
     post(text) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_fediverse_post)
-        throw new Error(
-          `permission '${Permissions.FediversePost}' not granted`,
-        );
+      const fns = hostFns("owncast_fediverse_post", Permissions.FediversePost);
       const offset = fns.owncast_fediverse_post(Memory.fromString(text).offset);
       if (offset == 0) return null;
       return JSON.parse(Memory.find(offset).readString());
@@ -648,30 +687,18 @@ const owncast = {
   },
   notifications: {
     discord(text) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_notify_discord)
-        throw new Error(
-          `permission '${Permissions.NotificationsSend}' not granted`,
-        );
+      const fns = hostFns("owncast_notify_discord", Permissions.NotificationsSend);
       fns.owncast_notify_discord(Memory.fromString(text).offset);
     },
     browserPush(payload) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_notify_browser_push)
-        throw new Error(
-          `permission '${Permissions.NotificationsSend}' not granted`,
-        );
+      const fns = hostFns("owncast_notify_browser_push", Permissions.NotificationsSend);
       const obj = typeof payload === "string" ? { title: payload } : payload;
       fns.owncast_notify_browser_push(
         Memory.fromString(JSON.stringify(obj)).offset,
       );
     },
     fediverse(payload) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_notify_fediverse)
-        throw new Error(
-          `permission '${Permissions.NotificationsSend}' not granted`,
-        );
+      const fns = hostFns("owncast_notify_fediverse", Permissions.NotificationsSend);
       fns.owncast_notify_fediverse(
         Memory.fromString(JSON.stringify(payload)).offset,
       );
@@ -679,17 +706,13 @@ const owncast = {
   },
   stream: {
     current() {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_stream_current)
-        throw new Error(`permission '${Permissions.ServerRead}' not granted`);
+      const fns = hostFns("owncast_stream_current", Permissions.ServerRead);
       const offset = fns.owncast_stream_current();
       if (offset == 0) return { online: false, viewers: 0 };
       return JSON.parse(Memory.find(offset).readString());
     },
     broadcaster() {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_stream_broadcaster)
-        throw new Error(`permission '${Permissions.ServerRead}' not granted`);
+      const fns = hostFns("owncast_stream_broadcaster", Permissions.ServerRead);
       const offset = fns.owncast_stream_broadcaster();
       if (offset == 0) return {};
       return JSON.parse(Memory.find(offset).readString());
@@ -697,41 +720,31 @@ const owncast = {
   },
   server: {
     info() {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_server_info)
-        throw new Error(`permission '${Permissions.ServerRead}' not granted`);
+      const fns = hostFns("owncast_server_info", Permissions.ServerRead);
       const offset = fns.owncast_server_info();
       if (offset == 0) return {};
       return JSON.parse(Memory.find(offset).readString());
     },
     socials() {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_server_socials)
-        throw new Error(`permission '${Permissions.ServerRead}' not granted`);
+      const fns = hostFns("owncast_server_socials", Permissions.ServerRead);
       const offset = fns.owncast_server_socials();
       if (offset == 0) return [];
       return JSON.parse(Memory.find(offset).readString());
     },
     emotes() {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_server_emotes)
-        throw new Error(`permission '${Permissions.ServerRead}' not granted`);
+      const fns = hostFns("owncast_server_emotes", Permissions.ServerRead);
       const offset = fns.owncast_server_emotes();
       if (offset == 0) return [];
       return JSON.parse(Memory.find(offset).readString());
     },
     federation() {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_server_federation)
-        throw new Error(`permission '${Permissions.ServerRead}' not granted`);
+      const fns = hostFns("owncast_server_federation", Permissions.ServerRead);
       const offset = fns.owncast_server_federation();
       if (offset == 0) return { enabled: false };
       return JSON.parse(Memory.find(offset).readString());
     },
     tags() {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_server_tags)
-        throw new Error(`permission '${Permissions.ServerRead}' not granted`);
+      const fns = hostFns("owncast_server_tags", Permissions.ServerRead);
       const offset = fns.owncast_server_tags();
       if (offset == 0) return [];
       return JSON.parse(Memory.find(offset).readString());
@@ -741,50 +754,36 @@ const owncast = {
     /** Read the current video/transcoding config: { latencyLevel, codec,
      *  variants }. Requires `videoconfig.read`. */
     read() {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_video_config_read)
-        throw new Error(
-          `permission '${Permissions.VideoConfigRead}' not granted`,
-        );
+      const fns = hostFns("owncast_video_config_read", Permissions.VideoConfigRead);
       const offset = fns.owncast_video_config_read();
       if (offset == 0) return { latencyLevel: 0, codec: "", variants: [] };
       return JSON.parse(Memory.find(offset).readString());
     },
     /** Apply a partial video config change. Pass any of { latencyLevel, codec,
-     *  variants }; omitted fields are left unchanged. Throws if the host
+     *  variants }, where omitted fields are left unchanged. Throws if the host
      *  rejects the config. Requires `videoconfig.write`. */
     write(config) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_video_config_write)
-        throw new Error(
-          `permission '${Permissions.VideoConfigWrite}' not granted`,
-        );
+      const fns = hostFns("owncast_video_config_write", Permissions.VideoConfigWrite);
       const offset = fns.owncast_video_config_write(
         Memory.fromString(JSON.stringify(config || {})).offset,
       );
-      if (offset == 0) throw new Error("videoConfig.write failed");
-      const result = JSON.parse(Memory.find(offset).readString());
-      if (!result.ok)
-        throw new Error(result.error || "videoConfig.write failed");
+      requireOperationResult(offset, "videoConfig.write failed");
     },
   },
   kv: {
     get(key) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_kv_get)
-        throw new Error(`permission '${Permissions.StorageKV}' not granted`);
+      const fns = hostFns("owncast_kv_get", Permissions.StorageKV);
       const offset = fns.owncast_kv_get(Memory.fromString(key).offset);
       if (offset == 0) return null;
       return Memory.find(offset).readString();
     },
     set(key, value) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_kv_set)
-        throw new Error(`permission '${Permissions.StorageKV}' not granted`);
-      fns.owncast_kv_set(
+      const fns = hostFns("owncast_kv_set", Permissions.StorageKV);
+      const offset = fns.owncast_kv_set(
         Memory.fromString(key).offset,
         Memory.fromString(String(value)).offset,
       );
+      requireOperationResult(offset, "kv.set failed");
     },
     // getJSON/setJSON are convenience wrappers over the string-only store, so
     // plugins don't reimplement JSON.parse/stringify for every stored object.
@@ -837,9 +836,7 @@ const owncast = {
   },
   events: {
     emit(eventType, payload) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_emit_event)
-        throw new Error(`permission '${Permissions.EventsEmit}' not granted`);
+      const fns = hostFns("owncast_emit_event", Permissions.EventsEmit);
       fns.owncast_emit_event(
         Memory.fromString(eventType).offset,
         Memory.fromString(JSON.stringify(payload)).offset,
@@ -847,43 +844,40 @@ const owncast = {
     },
   },
   actions: {
-    // Append one or more action buttons to the plugin's effective list
-    // (manifest.actions ++ runtime additions). Accepts a single button
-    // object or an array. The host validates each entry (title
-    // required, exactly one of url/html, relative URLs rewritten into
-    // this plugin's namespace, cross-plugin URLs rejected) and persists
-    // the result, so the next /api/config request returns the longer
-    // list. Requires 'ui.modify'.
+    // Append one or more action buttons to the plugin's effective list.
+    // The host validates and persists the list, returning { error? }.
     add(actions) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_add_actions)
-        throw permError("owncast.actions.add", Permissions.UIModify);
+      const fns = hostFns("owncast_add_actions", Permissions.UIModify);
       const list = Array.isArray(actions) ? actions : [actions];
-      fns.owncast_add_actions(Memory.fromString(JSON.stringify(list)).offset);
+      requireOperationResult(
+        fns.owncast_add_actions(
+          Memory.fromString(JSON.stringify(list)).offset,
+        ),
+        "owncast.actions.add failed",
+      );
     },
     // Drop the runtime additions so only manifest.actions remain in
     // the effective list on the next /api/config request. Requires
     // 'ui.modify'.
     clear() {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_clear_actions)
-        throw permError("owncast.actions.clear", Permissions.UIModify);
-      fns.owncast_clear_actions();
+      const fns = hostFns("owncast_clear_actions", Permissions.UIModify);
+      requireOperationResult(
+        fns.owncast_clear_actions(),
+        "owncast.actions.clear failed",
+      );
     },
   },
   sse: {
     // send(channel, event, data) pushes one Server-Sent-Event to every
     // browser connected to this plugin's /plugins/<name>/_sse/<channel>
     // stream. `event` is the SSE event name (browser side:
-    // source.addEventListener(event, ...)); pass "" for the default
+    // source.addEventListener(event, ...)). Pass "" for the default
     // "message" event. `data` is sent as-is if it's a string, otherwise
     // JSON-stringified. Fire-and-forget: returns immediately, and frames to
     // a slow client are dropped rather than blocking the plugin. Requires
     // the 'http.sse' permission.
     send(channel, event, data) {
-      const fns = Host.getFunctions();
-      if (!fns.owncast_sse_send)
-        throw new Error(`permission '${Permissions.HttpSSE}' not granted`);
+      const fns = hostFns("owncast_sse_send", Permissions.HttpSSE);
       const payload = typeof data === "string" ? data : JSON.stringify(data);
       fns.owncast_sse_send(
         Memory.fromString(channel || "").offset,
@@ -895,7 +889,7 @@ const owncast = {
   timer: {
     // setTimeout(fn, ms) runs fn once after ~ms milliseconds. setInterval
     // repeats until clear(id). The host drives the schedule (the sandbox has
-    // no setTimeout); your callback runs in this instance when it fires.
+    // no setTimeout). Your callback runs in this instance when it fires.
     // Returns an id for clear(). Very small delays are clamped up by the host,
     // and there's a per-plugin cap on pending timers (throws past it).
     // Note: timers are in-memory and do not survive a plugin reload or a host
@@ -945,11 +939,21 @@ function dispatchPageContent(req) {
   return registered.onPageContent(req) || "";
 }
 
+function dispatchPageStyles() {
+  if (!registered || !isFn(registered.onPageStyles)) return "";
+  return registered.onPageStyles() || "";
+}
+
+function dispatchPageScripts() {
+  if (!registered || !isFn(registered.onPageScripts)) return "";
+  return registered.onPageScripts() || "";
+}
+
 module.exports = {
   definePlugin,
-  defineCommands,
   owncast,
   filter,
+  authCheck,
   FilterAction,
   Events,
   Permissions,
@@ -958,6 +962,9 @@ module.exports = {
   dispatchEvent,
   dispatchFilter,
   dispatchHttp,
+  dispatchAuthCheck,
   dispatchTabContent,
   dispatchPageContent,
+  dispatchPageStyles,
+  dispatchPageScripts,
 };