@openbrf/plugin-sdk 0.0.0-stage → 1.0.0

package/src/host.ts

@@ -0,0 +1,240 @@
+import type { PluginActions } from "./actions.ts";
+import type { PluginPermission } from "./permissions.ts";
+import type { PluginSettingsValues } from "./settings-schema.ts";
+
+/**
+ * The host services a plugin receives.
+ *
+ * Every service is present on the object whether or not the plugin declared
+ * the permission it needs; the ones it did not declare throw
+ * PluginPermissionError on use. Handing out nulls instead would push a
+ * null-check into every call site of a plugin that did declare the permission,
+ * for the sake of a case the plugin author has already ruled out by writing
+ * the manifest. `permissions` is on the object for the plugin that genuinely
+ * wants to degrade rather than fail.
+ */
+
+export class PluginPermissionError extends Error {
+  constructor(
+    readonly pluginId: string,
+    readonly permission: PluginPermission,
+  ) {
+    super(
+      `Plugin "${pluginId}" used a service requiring the "${permission}" ` +
+        `permission, which its manifest does not declare.`,
+    );
+    this.name = "PluginPermissionError";
+  }
+}
+
+/**
+ * Writes to the host's log, tagged with the plugin's id.
+ *
+ * A plugin must not reach for console: its output would be indistinguishable
+ * from the core's, and an operator reading a log needs to know which plugin
+ * produced a line before they can decide whether to disable it.
+ */
+export interface PluginLogger {
+  debug(message: string): void;
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string, cause?: unknown): void;
+}
+
+/** The plugin's own settings, validated against its declared settingsSchema. */
+export interface PluginSettings {
+  /**
+   * The stored values, with declared defaults applied. Reads the current
+   * values on each call rather than caching, so a change made in the admin
+   * interface reaches a long-running job without a restart.
+   */
+  read(): Promise<PluginSettingsValues>;
+}
+
+export interface PluginMailMessage {
+  to: string;
+  subject: string;
+  /**
+   * The body, as text.
+   *
+   * Blank lines separate paragraphs; the host renders them in the house style
+   * and escapes them. There is no markup parameter, and that is the point: a
+   * message sent here leaves under the cooperative's own address and passes
+   * its DKIM signature, so a link, an image or a styled block a plugin put in
+   * it would be a link, an image or a styled block the cooperative appears to
+   * have written. A plugin that interpolates a resident's own text into a
+   * body - the ordinary case, and the one that actually happens - cannot turn
+   * it into markup from here.
+   */
+  text: string;
+}
+
+/**
+ * Sends mail through the instance's configured SMTP server.
+ *
+ * The from address is the instance's and is not a parameter: mail from a
+ * housing cooperative's system has to be attributable to the cooperative.
+ * Requires the mail:send permission.
+ */
+export interface PluginMail {
+  send(message: PluginMailMessage): Promise<void>;
+}
+
+export interface PluginSmsMessage {
+  /** The recipient's number in E.164 form. */
+  to: string;
+  /**
+   * The whole message, as text.
+   *
+   * SMS carries no markup, no subject and no alternative part, so what is
+   * written here is literally what the recipient reads. Its length is the
+   * plugin's own decision and is not bounded by the host: a text message is
+   * billed by length, and what a message may cost the association is the
+   * plugin's business to keep in hand rather than something a silent
+   * truncation can settle.
+   */
+  text: string;
+}
+
+/**
+ * Sends text messages through the instance's configured SMS provider.
+ *
+ * The sender the message presents is the instance's and is not a parameter,
+ * for the reason the mail from address is not one: a text message from a
+ * housing cooperative's system has to be attributable to the cooperative.
+ *
+ * An instance with no provider configured cannot send at all, and the send
+ * fails rather than being dropped. Having no provider is the ordinary state of
+ * a housing cooperative that only ever mails its members, so a plugin whose
+ * work depends on SMS should read `permissions` and degrade, or treat the
+ * failure as the answer. Requires the sms:send permission.
+ */
+export interface PluginSms {
+  send(message: PluginSmsMessage): Promise<void>;
+}
+
+/**
+ * Background work. Queue names are namespaced with the plugin's id by the
+ * host, so two plugins cannot collide on a name and no plugin can subscribe to
+ * a core queue. A name is 1-64 letters, digits, `_`, `.` or `-`; any other
+ * name is refused with a RangeError. Requires the jobs:schedule permission.
+ */
+export interface PluginJobs {
+  work<Data extends object>(
+    name: string,
+    handler: (data: Data) => Promise<void> | void,
+  ): Promise<void>;
+  send<Data extends object>(name: string, data: Data): Promise<void>;
+  sendAt<Data extends object>(
+    name: string,
+    data: Data,
+    runAt: Date,
+  ): Promise<void>;
+  schedule<Data extends object>(
+    name: string,
+    cron: string,
+    data: Data,
+  ): Promise<void>;
+}
+
+export interface PluginApartment {
+  id: string;
+  number: string;
+  floor: number | null;
+  address: { id: string; street: string; number: string };
+}
+
+export interface PluginResident {
+  personId: string;
+  name: string;
+  /** MEMBER holds the tenant-ownership; RESIDENT occupies without holding it. */
+  role: "MEMBER" | "RESIDENT";
+  apartment: PluginApartment | null;
+  movedInOn: string | null;
+  movedOutOn: string | null;
+  /** Present only with the addressBook:readContact permission. */
+  email?: string | null;
+  /** Present only with the addressBook:readContact permission. */
+  phone?: string | null;
+}
+
+export interface PluginOccupancySummary {
+  apartments: number;
+  /** Distinct persons with a current residency. */
+  residents: number;
+  /** Distinct persons holding a current tenant-ownership. */
+  members: number;
+}
+
+/**
+ * Reading the register, scoped to what the plugin declared.
+ *
+ * Three rules hold on every method here regardless of permission, because
+ * they are the product's own (plan section 4.4) and a plugin is not a reason
+ * to relax them: a person with protected personal data never appears, a
+ * personal identity number is never returned, and nothing is writable.
+ * Requires addressBook:read; the contact fields additionally require
+ * addressBook:readContact.
+ */
+export interface PluginAddressBook {
+  apartments(): Promise<PluginApartment[]>;
+  /** Current residencies only. Moved-out rows are not plugin business. */
+  residents(): Promise<PluginResident[]>;
+  summary(): Promise<PluginOccupancySummary>;
+}
+
+/**
+ * The host object a plugin's module factory receives.
+ *
+ * It is late-bound: the services behind it are the application's own, and the
+ * application is built after the factory has run. Every member below is
+ * therefore usable from a lifecycle hook (`onModuleInit` onwards), a guard or
+ * a request handler, and not from a provider's constructor - which is where
+ * NestJS asks for work to be done in any case. A call made too early throws
+ * rather than reading a half-built application.
+ *
+ * A plugin the board has switched off keeps its object, and every service on
+ * it refuses. Disabling has to bite immediately, and a plugin whose own timer
+ * outlived the switch must not still be reading the register through it.
+ */
+export interface PluginHost {
+  /** The plugin's own id, as declared in its manifest. */
+  id: string;
+  /** What the manifest declared and the board consented to. */
+  permissions: readonly PluginPermission[];
+  logger: PluginLogger;
+  settings: PluginSettings;
+  mail: PluginMail;
+  sms: PluginSms;
+  jobs: PluginJobs;
+  addressBook: PluginAddressBook;
+  /**
+   * The actions this plugin declared, and dispatch for every action it may
+   * reach.
+   *
+   * Added after this contract version shipped, so a plugin built against a
+   * newer host than the one it is installed on must feature-detect before
+   * using it - `isSupportedApiVersion` cannot see a member added to an
+   * interface, and the failure would otherwise surface as a load-failed
+   * finding with the message deliberately withheld.
+   */
+  actions: PluginActions;
+}
+
+/**
+ * A host service was used before the application finished starting, or after
+ * the plugin stopped serving.
+ *
+ * Both cases are the plugin reaching for the host at a moment the host cannot
+ * answer for: the first is work done in a constructor that belongs in
+ * `onModuleInit`, the second is a plugin the board switched off.
+ */
+export class PluginHostUnavailableError extends Error {
+  constructor(
+    readonly pluginId: string,
+    readonly detail: string,
+  ) {
+    super(`Plugin "${pluginId}" used a host service ${detail}`);
+    this.name = "PluginHostUnavailableError";
+  }
+}

package/src/index.ts

@@ -0,0 +1,123 @@
+/**
+ * @openbrf/plugin-sdk - the public plugin contract for Open BRF.
+ *
+ * A plugin depends on this package for types and for the manifest schema it
+ * validates itself against in its own CI. At runtime the host injects
+ * everything a plugin uses (see PluginHost), so nothing exported here needs to
+ * be resolvable from inside an installed plugin directory - which is what lets
+ * a plugin ship as a self-contained bundle (ADR 0003).
+ */
+
+export {
+  ACTION_CHANNELS,
+  ACTION_EFFECTS,
+  ACTION_NAME_PATTERN,
+  ACTION_PERSONAL_DATA,
+  ACTION_SURFACES,
+  type ActionChannel,
+  type ActionClient,
+  type ActionContext,
+  type ActionDefinition,
+  type ActionEffect,
+  type ActionErrorSpec,
+  type ActionPersonalData,
+  type ActionPrincipal,
+  type ActionRequest,
+  type ActionSummary,
+  type ActionSurface,
+  type PluginActionFilter,
+  type PluginActionRegistration,
+  type PluginActions,
+} from "./actions.ts";
+export {
+  actionInputJsonSchema,
+  actionOutputJsonSchema,
+  isHostZodSchema,
+} from "./action-schema.ts";
+export {
+  isSupportedApiVersion,
+  PLUGIN_API_VERSION,
+  SUPPORTED_PLUGIN_API_VERSIONS,
+} from "./api-version.ts";
+export {
+  type Catalog,
+  type CatalogArtifact,
+  catalogArtifactSchema,
+  type CatalogEntry,
+  catalogEntrySchema,
+  type CatalogParseResult,
+  type CatalogPluginEntry,
+  catalogPluginEntrySchema,
+  catalogSchema,
+  type CatalogThemeEntry,
+  catalogThemeEntrySchema,
+  type LocalizedText,
+  parseCatalogIndex,
+} from "./catalog.ts";
+export { definePlugin } from "./define-plugin.ts";
+export { formatSha512, IntegrityError, parseSha512 } from "./integrity.ts";
+export {
+  PLUGIN_FINDING_REASONS,
+  type PluginFindingDetail,
+  type PluginFindingReason,
+} from "./findings.ts";
+export {
+  type PluginAddressBook,
+  type PluginApartment,
+  type PluginHost,
+  PluginHostUnavailableError,
+  type PluginJobs,
+  type PluginLogger,
+  type PluginMail,
+  type PluginMailMessage,
+  type PluginOccupancySummary,
+  PluginPermissionError,
+  type PluginResident,
+  type PluginSettings,
+  type PluginSms,
+  type PluginSmsMessage,
+} from "./host.ts";
+export type { PluginModuleFactory } from "./module.ts";
+export {
+  assertPluginPackage,
+  composedActionName,
+  CURRENT_PLUGIN_API_VERSION,
+  type ManifestParseResult,
+  type PluginActionDeclaration,
+  pluginActionSchema,
+  pluginActionsSchema,
+  type PluginEntry,
+  pluginEntrySchema,
+  pluginIdSchema,
+  type PluginManifest,
+  pluginManifestSchema,
+  type PluginPackage,
+  pluginPackageSchema,
+  parsePluginPackage,
+} from "./manifest.ts";
+export {
+  HOST_SHARED_PACKAGES,
+  type PluginPackageContents,
+  pluginPackageProblems,
+} from "./package-check.ts";
+export type {
+  StandardSchemaIssue,
+  StandardSchemaResult,
+  StandardSchemaV1,
+} from "./standard-schema.ts";
+export {
+  isPluginPermission,
+  PLUGIN_PERMISSIONS,
+  PLUGIN_PERSONAL_DATA_CATEGORIES,
+  type PluginPermission,
+  type PluginPersonalDataCategory,
+} from "./permissions.ts";
+export {
+  defaultSettings,
+  type PluginSettingsField,
+  pluginSettingsFieldSchema,
+  type PluginSettingsSchema,
+  pluginSettingsSchema,
+  type PluginSettingsValues,
+  settingsValidator,
+} from "./settings-schema.ts";

package/src/integrity.ts

@@ -0,0 +1,125 @@
+/**
+ * How a catalog entry spells the sha512 digest of its tarball.
+ *
+ * The instance verifies the digest before it unpacks a download, and the
+ * catalog's own check verifies it before a listing is merged. Both must accept
+ * exactly the same spellings, or the catalog passes an entry the instance then
+ * refuses. So the parsing lives here, in the contract both depend on, and
+ * nowhere else.
+ *
+ * Written without `Buffer` or `node:crypto`: this package is also bundled into
+ * apps/web, a browser, where neither exists, and hashing itself stays with the
+ * caller. Base64 is decoded by hand rather than with `atob` so that padding and
+ * stray trailing bits are read as `Buffer` reads them, whatever the runtime.
+ */
+
+const SRI_PATTERN = /^sha512-([A-Za-z0-9+/]+)={0,2}$/;
+const HEX_PATTERN = /^[0-9a-f]{128}$/i;
+
+const SHA512_BYTES = 64;
+const BASE64_ALPHABET =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+/**
+ * Why a digest was refused. `malformed-digest` is a catalog entry that is
+ * written wrongly; `digest-mismatch` is bytes that are not the ones the entry
+ * names. Installers branch on the difference.
+ */
+export class IntegrityError extends Error {
+  constructor(
+    message: string,
+    readonly reason: "malformed-digest" | "digest-mismatch",
+  ) {
+    super(message);
+    this.name = "IntegrityError";
+  }
+}
+
+/**
+ * Normalizes a declared digest to raw bytes.
+ *
+ * Both spellings are accepted because both are what a publisher actually has
+ * to hand: `npm pack --json` reports the subresource-integrity form
+ * (`sha512-<base64>`), while `sha512sum` prints hex. Requiring one would mean
+ * every catalog entry is transcribed by hand from the other, which is how a
+ * digest ends up wrong in a way nobody notices until an install fails.
+ *
+ * @throws IntegrityError with reason `malformed-digest`.
+ */
+export function parseSha512(declared: string): Uint8Array {
+  const trimmed = declared.trim();
+
+  const sri = SRI_PATTERN.exec(trimmed);
+  if (sri !== null) {
+    const bytes = fromBase64(sri[1] ?? "");
+    if (bytes.length !== SHA512_BYTES) {
+      throw new IntegrityError(
+        "A sha512 digest is 64 bytes; this one is not.",
+        "malformed-digest",
+      );
+    }
+    return bytes;
+  }
+
+  if (HEX_PATTERN.test(trimmed)) {
+    return fromHex(trimmed);
+  }
+
+  throw new IntegrityError(
+    'Expected a digest written as "sha512-<base64>" or 128 hex characters.',
+    "malformed-digest",
+  );
+}
+
+/** The subresource-integrity spelling, which is what a catalog entry carries. */
+export function formatSha512(digest: Uint8Array): string {
+  return `sha512-${toBase64(digest)}`;
+}
+
+function fromHex(hex: string): Uint8Array {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let index = 0; index < bytes.length; index += 1) {
+    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * Standard base64 without its padding, which the caller has already split off.
+ * Stray trailing bits are dropped, as `Buffer.from(_, "base64")` drops them.
+ */
+function fromBase64(characters: string): Uint8Array {
+  const bytes = new Uint8Array(Math.floor((characters.length * 6) / 8));
+  let accumulator = 0;
+  let bits = 0;
+  let written = 0;
+
+  for (const character of characters) {
+    accumulator = (accumulator << 6) | BASE64_ALPHABET.indexOf(character);
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes[written] = (accumulator >> bits) & 0xff;
+      written += 1;
+      accumulator &= (1 << bits) - 1;
+    }
+  }
+  return bytes;
+}
+
+function toBase64(bytes: Uint8Array): string {
+  let encoded = "";
+  for (let index = 0; index < bytes.length; index += 3) {
+    const first = bytes[index] ?? 0;
+    const second = bytes[index + 1] ?? 0;
+    const third = bytes[index + 2] ?? 0;
+    const group = (first << 16) | (second << 8) | third;
+    const remaining = bytes.length - index;
+
+    encoded += BASE64_ALPHABET.charAt((group >> 18) & 63);
+    encoded += BASE64_ALPHABET.charAt((group >> 12) & 63);
+    encoded += remaining > 1 ? BASE64_ALPHABET.charAt((group >> 6) & 63) : "=";
+    encoded += remaining > 2 ? BASE64_ALPHABET.charAt(group & 63) : "=";
+  }
+  return encoded;
+}