@skillcdn/console 0.4.1 → 0.4.3

package/src/plugin/bridge.ts

@@ -0,0 +1,314 @@
+// The messages between the console's page and a plugin's frame (docs/specs/plugins.md, "The
+// bridge"): every message `{ v: 1, t, ... }`, the page accepting the frame's window alone, the
+// frame the console's origin alone. The shapes and their guards, with no DOM in them, so that the
+// page's side and the frame's side read the same words and the tests need no browser.
+
+export const PLUGIN_BRIDGE_VERSION = 1;
+
+/** What the frame may ask the page to perform, each under `/api/v1/plugins/<key>/` and nothing else. */
+export const BRIDGE_METHODS = [
+  "command",
+  "query",
+  "records.list",
+  "records.get",
+  "records.versions",
+  "files.get",
+  "files.put",
+] as const;
+
+export type BridgeMethod = (typeof BRIDGE_METHODS)[number];
+
+/** The kinds of `event` a frame may subscribe to: its plugin's records changed, a command ran, the plugin emitted. */
+export const BRIDGE_EVENT_KINDS = ["records", "command", "plugin"] as const;
+
+export type BridgeEventKind = (typeof BRIDGE_EVENT_KINDS)[number];
+
+export interface BridgePerson {
+  readonly id: string;
+  readonly login: string;
+  readonly name: string | null;
+  readonly language: string;
+  readonly admin: boolean;
+}
+
+/** What the page tells the frame once it is ready: who looks, at what, in which words and colours. */
+export interface BridgeInit {
+  readonly v: 1;
+  readonly t: "init";
+  readonly plugin: { readonly key: string; readonly version: string };
+  readonly page?: string;
+  readonly widget?: string;
+  readonly project: { readonly key: string; readonly name: string } | null;
+  readonly person: BridgePerson;
+  readonly roles: readonly string[];
+  /** What follows the page's key in the address. */
+  readonly path: string;
+  readonly language: string;
+  /** The console's computed design tokens, `--sc-*`. */
+  readonly theme: Readonly<Record<string, string>>;
+}
+
+export interface BridgeError {
+  readonly code: string;
+  readonly message: string;
+  readonly data?: unknown;
+}
+
+export interface BridgeResult {
+  readonly v: 1;
+  readonly t: "result";
+  readonly id: string;
+  readonly ok: boolean;
+  readonly value?: unknown;
+  readonly error?: BridgeError;
+}
+
+export interface BridgeEvent {
+  readonly v: 1;
+  readonly t: "event";
+  readonly kind: BridgeEventKind;
+  readonly data: unknown;
+}
+
+export interface BridgeTheme {
+  readonly v: 1;
+  readonly t: "theme";
+  readonly theme: Readonly<Record<string, string>>;
+}
+
+export interface BridgePath {
+  readonly v: 1;
+  readonly t: "path";
+  readonly path: string;
+}
+
+export type BridgeToFrame = BridgeInit | BridgeResult | BridgeEvent | BridgeTheme | BridgePath;
+
+export interface BridgeReady {
+  readonly v: 1;
+  readonly t: "ready";
+}
+
+export interface BridgeCall {
+  readonly v: 1;
+  readonly t: "call";
+  readonly id: string;
+  readonly method: BridgeMethod;
+  readonly params: unknown;
+}
+
+export interface BridgeNavigate {
+  readonly v: 1;
+  readonly t: "navigate";
+  readonly path: string;
+}
+
+export interface BridgeResize {
+  readonly v: 1;
+  readonly t: "resize";
+  readonly height: number;
+}
+
+export interface BridgeTitle {
+  readonly v: 1;
+  readonly t: "title";
+  readonly text: string;
+}
+
+export interface BridgeDownload {
+  readonly v: 1;
+  readonly t: "download";
+  readonly id: string;
+}
+
+export interface BridgeSubscribe {
+  readonly v: 1;
+  readonly t: "subscribe";
+  readonly kinds: readonly BridgeEventKind[];
+}
+
+export type BridgeToPage =
+  | BridgeReady
+  | BridgeCall
+  | BridgeNavigate
+  | BridgeResize
+  | BridgeTitle
+  | BridgeDownload
+  | BridgeSubscribe;
+
+/** A path of the console's, as `navigate` and `path` carry one: absolute, no scheme, no host, one line. */
+export const MAX_BRIDGE_PATH_LENGTH = 2048;
+export const MAX_BRIDGE_TITLE_LENGTH = 200;
+const MAX_ID_LENGTH = 128;
+const MAX_THEME_TOKENS = 500;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isLine(value: unknown, max: number): value is string {
+  return (
+    typeof value === "string" && value.length > 0 && value.length <= max && !/[\r\n]/.test(value)
+  );
+}
+
+/** True for a path the page may follow: within the console, never a URL. */
+export function isBridgePath(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length <= MAX_BRIDGE_PATH_LENGTH &&
+    value.startsWith("/") &&
+    !value.startsWith("//") &&
+    !/[\s\\]/.test(value)
+  );
+}
+
+function isTheme(value: unknown): value is Record<string, string> {
+  if (!isRecord(value)) {
+    return false;
+  }
+  const entries = Object.entries(value);
+  return (
+    entries.length <= MAX_THEME_TOKENS &&
+    entries.every(
+      ([token, text]) =>
+        /^--sc-[a-z0-9-]+$/.test(token) && typeof text === "string" && text.length <= 200,
+    )
+  );
+}
+
+function isEnvelope(value: unknown): value is Record<string, unknown> & { t: string } {
+  return isRecord(value) && value.v === PLUGIN_BRIDGE_VERSION && typeof value.t === "string";
+}
+
+/** True for a message the frame may act on, as the console's page sends them. */
+export function isBridgeToFrame(value: unknown): value is BridgeToFrame {
+  if (!isEnvelope(value)) {
+    return false;
+  }
+  switch (value.t) {
+    case "init":
+      return (
+        isRecord(value.plugin) &&
+        isLine(value.plugin.key, 32) &&
+        isLine(value.plugin.version, 64) &&
+        (value.page === undefined || isLine(value.page, 32)) &&
+        (value.widget === undefined || isLine(value.widget, 32)) &&
+        (value.project === null ||
+          (isRecord(value.project) &&
+            isLine(value.project.key, 64) &&
+            typeof value.project.name === "string")) &&
+        isRecord(value.person) &&
+        typeof value.person.id === "string" &&
+        typeof value.person.login === "string" &&
+        (value.person.name === null || typeof value.person.name === "string") &&
+        typeof value.person.language === "string" &&
+        typeof value.person.admin === "boolean" &&
+        Array.isArray(value.roles) &&
+        value.roles.every((role) => typeof role === "string") &&
+        typeof value.path === "string" &&
+        value.path.length <= MAX_BRIDGE_PATH_LENGTH &&
+        typeof value.language === "string" &&
+        isTheme(value.theme)
+      );
+    case "result":
+      return (
+        isLine(value.id, MAX_ID_LENGTH) &&
+        typeof value.ok === "boolean" &&
+        (value.error === undefined ||
+          (isRecord(value.error) &&
+            typeof value.error.code === "string" &&
+            typeof value.error.message === "string"))
+      );
+    case "event":
+      return (
+        typeof value.kind === "string" &&
+        (BRIDGE_EVENT_KINDS as readonly string[]).includes(value.kind)
+      );
+    case "theme":
+      return isTheme(value.theme);
+    case "path":
+      return typeof value.path === "string" && value.path.length <= MAX_BRIDGE_PATH_LENGTH;
+    default:
+      return false;
+  }
+}
+
+/** True for a message the page may act on, as a frame sends them; anything else is dropped unread. */
+export function isBridgeToPage(value: unknown): value is BridgeToPage {
+  if (!isEnvelope(value)) {
+    return false;
+  }
+  switch (value.t) {
+    case "ready":
+      return true;
+    case "call":
+      return (
+        isLine(value.id, MAX_ID_LENGTH) &&
+        typeof value.method === "string" &&
+        (BRIDGE_METHODS as readonly string[]).includes(value.method) &&
+        isRecord(value.params)
+      );
+    case "navigate":
+      return isBridgePath(value.path);
+    case "resize":
+      return typeof value.height === "number" && Number.isFinite(value.height) && value.height >= 0;
+    case "title":
+      return (
+        typeof value.text === "string" &&
+        value.text.length <= MAX_BRIDGE_TITLE_LENGTH &&
+        !/[\r\n]/.test(value.text)
+      );
+    case "download":
+      return isLine(value.id, MAX_ID_LENGTH);
+    case "subscribe":
+      return (
+        Array.isArray(value.kinds) &&
+        value.kinds.length <= BRIDGE_EVENT_KINDS.length &&
+        value.kinds.every(
+          (kind) =>
+            typeof kind === "string" && (BRIDGE_EVENT_KINDS as readonly string[]).includes(kind),
+        )
+      );
+    default:
+      return false;
+  }
+}
+
+/** The result of a command as the frame receives it, the same shape the command line prints from. */
+export interface BridgeCommandResult {
+  readonly kind: "command" | "query";
+  readonly text: string;
+  readonly data: unknown;
+  readonly waiting: string | null;
+}
+
+/** What `records.list` and `records.get` carry in `params`, as the page sends them on. */
+export interface BridgeRecordsListParams {
+  readonly collection: string;
+  readonly where?: Readonly<Record<string, unknown>>;
+  readonly order?: string;
+  readonly limit?: number;
+  readonly after?: string;
+  readonly q?: string;
+  readonly project?: string;
+}
+
+export interface BridgeRecordsGetParams {
+  readonly collection: string;
+  readonly id: string;
+  readonly version?: number;
+}
+
+export interface BridgeFilesPutParams {
+  readonly bytes: ArrayBuffer;
+  readonly name: string;
+  readonly type: string;
+}
+
+/** What `files.get` answers: the bytes, transferred, with the file's name and type. */
+export interface BridgeFile {
+  readonly name: string;
+  readonly type: string;
+  readonly bytes: ArrayBuffer;
+}

package/src/plugin/capabilities.ts

@@ -0,0 +1,150 @@
+// The catalogue of what a plugin may ask of a console (docs/specs/plugins.md, "Capabilities"):
+// declared in the manifest, consented to by an administrator when the plugin is enabled, enforced
+// by the parent on every call. Each carries the sentence an administrator reads before consenting,
+// and the reach of a plugin that turns out malicious and holds it.
+
+/** The capabilities that take no parameter. */
+export const PLUGIN_CAPABILITIES = [
+  "files",
+  "people:read",
+  "people:read:all",
+  "projects:read",
+  "projects:read:all",
+  "board:read",
+  "board:tasks",
+  "board:decisions",
+  "board:documents",
+  "events:console",
+  "events:plugins",
+  "jobs",
+  "endpoints",
+  "storage:sql",
+] as const;
+
+export type PluginCapability = (typeof PLUGIN_CAPABILITIES)[number];
+
+/** The capabilities that carry a parameter: a host to reach, a plugin to call. */
+export const PLUGIN_CAPABILITY_PREFIXES = ["outbound:", "plugins:"] as const;
+
+/** A host as `outbound:<host>` names one: a name, or `*.` before a name for its subdomains. Never a port, never a path. */
+const OUTBOUND_HOST = /^(?:\*\.)?(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+
+const PLUGIN_KEY = /^[a-z][a-z0-9-]{1,31}$/;
+
+export interface CapabilityWords {
+  /** What it opens, as the administrator reads it before consenting. */
+  readonly opens: string;
+  /** The reach of a plugin that turns out malicious and holds it. */
+  readonly reach: string;
+}
+
+/** What each capability opens and what it risks, in the words of the specification. */
+export const CAPABILITY_WORDS: Readonly<Record<PluginCapability, CapabilityWords>> = {
+  files: {
+    opens: "files on its records, within the bytes the deployment allows a plugin",
+    reach: "storage filled to the bound",
+  },
+  "people:read": {
+    opens: "the people the caller may see, as the person",
+    reach: "the names and logins its role holders may see anyway",
+  },
+  "people:read:all": {
+    opens: "everyone in the workspace, for its jobs and hooks too",
+    reach: "the directory",
+  },
+  "projects:read": {
+    opens: "the projects and members the caller may see",
+    reach: "what the person sees",
+  },
+  "projects:read:all": {
+    opens: "every project and its members",
+    reach: "the projects and who is in them",
+  },
+  "board:read": {
+    opens:
+      "the tasks, decisions, runs, documents and events of its board projects, and of the project a call is on",
+    reach: "the content of those boards, to its role holders",
+  },
+  "board:tasks": {
+    opens: "tasks created in its projects; its own changed, closed and commented",
+    reach: "tasks that mislead; each marked as the plugin's, put away by anyone",
+  },
+  "board:decisions": {
+    opens: "decisions raised in its projects; the answers to its own read",
+    reach: "questions that mislead; never an answer",
+  },
+  "board:documents": {
+    opens: "pages written under plugins/<key>/ in its projects",
+    reach: "pages that mislead, in its folder",
+  },
+  "events:console": {
+    opens: "hooks on the console's events of its board projects",
+    reach: "when things happen on those boards",
+  },
+  "events:plugins": {
+    opens: "hooks on the events other plugins emit",
+    reach: "what they publish",
+  },
+  jobs: {
+    opens: "runs on a schedule",
+    reach: "time, within the bound",
+  },
+  endpoints: {
+    opens: "inbound requests under its path, a person's or a webhook's",
+    reach: "input it accepts without verifying; the rate limit holds",
+  },
+  "storage:sql": {
+    opens: "a schema and a login role of its own in the console's database",
+    reach: "statements up to the timeout, within its schema",
+  },
+};
+
+/** True for a capability the catalogue knows, parameter included. */
+export function isPluginCapability(value: string): boolean {
+  if ((PLUGIN_CAPABILITIES as readonly string[]).includes(value)) {
+    return true;
+  }
+  if (value.startsWith("outbound:")) {
+    return OUTBOUND_HOST.test(value.slice("outbound:".length));
+  }
+  if (value.startsWith("plugins:")) {
+    return PLUGIN_KEY.test(value.slice("plugins:".length));
+  }
+  return false;
+}
+
+/** The sentences for a capability, parameter included; nothing for one the catalogue does not know. */
+export function capabilityWords(capability: string): CapabilityWords | undefined {
+  if ((PLUGIN_CAPABILITIES as readonly string[]).includes(capability)) {
+    return CAPABILITY_WORDS[capability as PluginCapability];
+  }
+  if (capability.startsWith("outbound:") && isPluginCapability(capability)) {
+    const host = capability.slice("outbound:".length);
+    return {
+      opens: `requests to ${host}, a public address, over https`,
+      reach: `what it may read, sent to ${host}; a cost there`,
+    };
+  }
+  if (capability.startsWith("plugins:") && isPluginCapability(capability)) {
+    const key = capability.slice("plugins:".length);
+    return {
+      opens: `the API of the plugin ${key}, as the caller`,
+      reach: "what that API gives the caller",
+    };
+  }
+  return undefined;
+}
+
+/** True when the request's host is within what `outbound:<host>` names: the host itself, or a subdomain where the capability starts with `*.`. */
+export function outboundAllows(capability: string, host: string): boolean {
+  if (!capability.startsWith("outbound:") || !isPluginCapability(capability)) {
+    return false;
+  }
+  const named = capability.slice("outbound:".length);
+  const lower = host.toLowerCase();
+  if (named.startsWith("*.")) {
+    const domain = named.slice(2);
+    return lower.endsWith(`.${domain}`) && lower.length > domain.length + 1;
+  }
+  return lower === named;
+}