@openbrf/plugin-sdk 0.0.0-stage → 1.2.0

package/src/records.ts

@@ -0,0 +1,172 @@
+/**
+ * A plugin's own records (ADR 0033).
+ *
+ * A small keyed store: JSON values under a collection and a key, belonging to
+ * the plugin and to nothing else. It is for what a plugin has of its own to
+ * remember and cannot fit into a settings form - a list of screens, each with
+ * its own layout and rotation - and never for people. The data subject access
+ * report, purging, erasure and restriction all read the core's own tables, and
+ * a plugin's JSON is opaque to every one of them, so a name, an email address
+ * or anything copied out of the register kept here would be data the
+ * association holds and cannot report, purge or restrict. The host cannot tell
+ * a name from a label, so the rule is declared rather than enforced, with one
+ * exception: a personal identity number is refused on every write.
+ *
+ * The errors below are thrown by the host's copy of this package. A plugin
+ * imports the SDK for its types only, so it tells them apart by `name` rather
+ * than with `instanceof`.
+ */
+
+/** A value JSON can carry. */
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+/**
+ * A collection: lowercase letters, digits and single hyphens, at most 32
+ * characters, starting and ending with a letter or a digit.
+ */
+export const PLUGIN_RECORD_COLLECTION_PATTERN =
+  /^(?=.{1,32}$)[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** A key: 1 to 128 letters, digits, `.`, `_`, `:` or `-`. */
+export const PLUGIN_RECORD_KEY_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+
+/** What one plugin may hold, and the most one call reads. */
+export const PLUGIN_RECORD_LIMITS = {
+  /** Bytes of one value, serialised as JSON in UTF-8. */
+  valueBytes: 64 * 1024,
+  /** Records per plugin, across every collection. */
+  records: 10_000,
+  /** Bytes per plugin, across every collection, counted as for one value. */
+  totalBytes: 16 * 1024 * 1024,
+  /** Records one `list` returns, and its default. */
+  listLimit: 200,
+  /**
+   * Writes of one plugin the host holds at once, the one under way and those
+   * waiting for their turn. A write sent past it is refused, not held.
+   */
+  queuedWrites: 100,
+} as const;
+
+export interface PluginRecord<Value extends JsonValue = JsonValue> {
+  readonly collection: string;
+  readonly key: string;
+  readonly value: Value;
+  /**
+   * A counter, 1 when the record is written first and one more on every write
+   * after that. Not `updatedAt`, because two writes inside one millisecond
+   * carry the same time.
+   */
+  readonly revision: number;
+  /** When the record was last written, as an ISO 8601 instant. */
+  readonly updatedAt: string;
+}
+
+/**
+ * The plugin's own records. Needs no permission, and refuses while the plugin
+ * is switched off, as every host service does.
+ *
+ * A collection or a key outside its pattern is refused with a RangeError, and a
+ * value JSON cannot carry exactly - `undefined`, a function, `NaN`, a `Date`, a
+ * class instance, a lone surrogate or a NUL character - with a TypeError.
+ */
+export interface PluginRecords {
+  get<Value extends JsonValue>(
+    collection: string,
+    key: string,
+  ): Promise<PluginRecord<Value> | null>;
+
+  /**
+   * In key order, from after `after` when it is given. At most 200 per call,
+   * which is also the default.
+   */
+  list<Value extends JsonValue>(
+    collection: string,
+    options?: { after?: string; limit?: number },
+  ): Promise<readonly PluginRecord<Value>[]>;
+
+  /**
+   * Writes a value. With `expectedRevision`, only over that revision, and
+   * `null` means only where there is no record yet; otherwise it throws
+   * PluginRecordConflictError.
+   *
+   * A value carrying a personal identity number, in a string, a property name
+   * or a number, is refused with PluginRecordIdentityNumberError. A value
+   * over 64 KiB, and a write that would take the plugin past 10 000 records
+   * or 16 MiB, is refused with PluginRecordLimitError, and so is any write,
+   * an overwrite too, sent while 100 of the plugin's writes are already held,
+   * the one under way and those waiting.
+   */
+  put<Value extends JsonValue>(
+    collection: string,
+    key: string,
+    value: Value,
+    options?: { expectedRevision?: number | null },
+  ): Promise<PluginRecord<Value>>;
+
+  /**
+   * True when there was a record to delete. With `expectedRevision`, only that
+   * revision is deleted, and another one throws PluginRecordConflictError; no
+   * record at all is still `false`.
+   */
+  delete(
+    collection: string,
+    key: string,
+    options?: { expectedRevision?: number },
+  ): Promise<boolean>;
+}
+
+/** A write's `expectedRevision` did not match the record it found. */
+export class PluginRecordConflictError extends Error {
+  constructor(
+    readonly pluginId: string,
+    /** The revision the store holds, or null when it holds no record. */
+    readonly actualRevision: number | null,
+  ) {
+    super(
+      `Plugin "${pluginId}" wrote a record over a revision it no longer has.`,
+    );
+    this.name = "PluginRecordConflictError";
+  }
+}
+
+export type PluginRecordLimit =
+  "valueBytes" | "records" | "totalBytes" | "queuedWrites";
+
+/**
+ * A write, or a delete queued behind the writes, was past one of
+ * {@link PLUGIN_RECORD_LIMITS}, and nothing was changed.
+ */
+export class PluginRecordLimitError extends Error {
+  constructor(
+    readonly pluginId: string,
+    readonly limit: PluginRecordLimit,
+  ) {
+    super(
+      `Plugin "${pluginId}" was refused a record operation past its ${limit} ` +
+        `limit of ${String(PLUGIN_RECORD_LIMITS[limit])}.`,
+    );
+    this.name = "PluginRecordLimitError";
+  }
+}
+
+/**
+ * A write carried a personal identity number.
+ *
+ * Neither the collection, the key nor the number is in the message: the error
+ * reaches the log, and the number is what the refusal is keeping out of it.
+ */
+export class PluginRecordIdentityNumberError extends Error {
+  constructor(readonly pluginId: string) {
+    super(
+      `Plugin "${pluginId}" wrote a record carrying a personal identity ` +
+        "number, which a plugin's records may not hold.",
+    );
+    this.name = "PluginRecordIdentityNumberError";
+  }
+}

package/src/require-capability.ts

@@ -0,0 +1,106 @@
+/**
+ * Raising a plugin route above the capability floor the host gives it.
+ *
+ * The host reads one metadata key off a controller and off each of its routes,
+ * and answers a request only for a person who holds every capability listed
+ * there. A plugin's controllers get a floor from the plugin's own permissions
+ * (see "Routes" in the plugin contract); `RequireCapability` is how a route
+ * asks for more.
+ *
+ * Written without `@nestjs/common` on purpose, for the reason `definePlugin` is
+ * an identity function: the SDK is bundled into the plugin, and an import of
+ * its own would have to be resolved from the data volume. NestJS's
+ * `SetMetadata` does no more than this, on the same global `Reflect` the host's
+ * copy of NestJS writes to.
+ */
+
+/** The metadata key the host reads a route's or a controller's capabilities from. */
+export const REQUIRED_CAPABILITIES_KEY = "openbrf:required-capabilities";
+
+/**
+ * Every capability name the host knows, which is what a route may require.
+ *
+ * Listed here, not derived, because the SDK cannot import the host. The host
+ * checks the list against its own capabilities in a test, so a capability
+ * added there is not missing here for long; until the SDK is released with it,
+ * a plugin that needs the new name is a type error rather than a typo caught
+ * at request time.
+ */
+export const PLUGIN_ROUTE_CAPABILITIES = [
+  "association:manage",
+  "association:read",
+  "addressBook:read",
+  "addressBook:write",
+  "memberRegister:read",
+  "apartmentRegister:read",
+  "protectedData:reveal",
+  "registerReport:export",
+  "invitation:send",
+  "signupRequest:decide",
+  "self:manage",
+  "residentDirectory:read",
+  "issues:handle",
+  "issues:report",
+  "issues:configure",
+  "documents:manage",
+  "site:manage",
+  "news:comment",
+  "boardPosition:manage",
+  "bookings:book",
+  "bookings:manage",
+  "bookings:configure",
+  "events:manage",
+  "events:attend",
+  "systemRole:manage",
+  "motions:submit",
+  "motions:handle",
+  "meetings:manage",
+  "memberCharges:manage",
+  "fees:manage",
+  "dataProtection:manage",
+  "boardMailbox:handle",
+  "sublets:apply",
+  "sublets:handle",
+  "keyOrders:place",
+  "keyOrders:handle",
+  "chat:participate",
+  "chat:moderate",
+  "apartmentBinder:manage",
+] as const;
+
+/** A capability name a plugin route may require. */
+export type PluginRouteCapability = (typeof PLUGIN_ROUTE_CAPABILITIES)[number];
+
+/** The slice of `Reflect` that `reflect-metadata` adds, which NestJS loads. */
+interface MetadataReflect {
+  defineMetadata?: (key: string, value: unknown, target: object) => void;
+}
+
+/**
+ * Declares the capabilities a route requires. Several are combined with AND.
+ *
+ * Applied to a controller it covers every route in it. It can only add to the
+ * floor the host gives the plugin: a route cannot require less.
+ */
+export function RequireCapability(
+  ...capabilities: PluginRouteCapability[]
+): MethodDecorator & ClassDecorator {
+  return ((
+    target: object,
+    _key?: string | symbol,
+    descriptor?: PropertyDescriptor,
+  ) => {
+    const define = (Reflect as unknown as MetadataReflect).defineMetadata;
+    if (define === undefined) {
+      throw new Error(
+        "RequireCapability needs reflect-metadata, which @nestjs/common loads: import it before the controller.",
+      );
+    }
+    if (descriptor !== undefined) {
+      define(REQUIRED_CAPABILITIES_KEY, capabilities, descriptor.value);
+      return descriptor;
+    }
+    define(REQUIRED_CAPABILITIES_KEY, capabilities, target);
+    return target;
+  }) as MethodDecorator & ClassDecorator;
+}

package/src/settings-schema.ts

@@ -0,0 +1,334 @@
+import { z } from "zod";
+
+/**
+ * A plugin's settings form, declared rather than drawn.
+ *
+ * The host renders it, validates against it, and stores the result. A plugin
+ * therefore never ships a settings screen of its own, which is what keeps
+ * plugin settings looking like the rest of the product and keeps the values
+ * validated on the server rather than only in a form the plugin drew.
+ *
+ * Labels are i18n KEYS, resolved in the plugin's own namespace
+ * (`plugin-<id>`, merged at runtime from its locales/{sv,en}.json). Inline
+ * label text is deliberately not accepted: a manifest carrying English prose
+ * would put an untranslatable string on a Swedish-first screen, and the
+ * runtime merge already exists to hold that text.
+ */
+
+const settingsKeySchema = z
+  .string()
+  .min(1)
+  .max(64)
+  // A settings key becomes a JSON object key and a form field name. Keeping it
+  // to an identifier shape means a stored value can never collide with a
+  // prototype member or need escaping in either place.
+  .regex(/^[a-z][a-zA-Z0-9_]*$/, "must be a lowerCamelCase identifier");
+
+const translationKeySchema = z.string().min(1).max(200);
+
+const baseFieldSchema = z.object({
+  key: settingsKeySchema,
+  labelKey: translationKeySchema,
+  /** Help text under the field. Never the only carrier of a requirement. */
+  hintKey: translationKeySchema.optional(),
+  required: z.boolean().default(false),
+});
+
+const textFieldSchema = baseFieldSchema.extend({
+  type: z.literal("text"),
+  default: z.string().optional(),
+  minLength: z.int().min(0).optional(),
+  maxLength: z.int().min(1).max(10_000).optional(),
+});
+
+const numberFieldSchema = baseFieldSchema.extend({
+  type: z.literal("number"),
+  default: z.number().optional(),
+  min: z.number().optional(),
+  max: z.number().optional(),
+  integer: z.boolean().default(false),
+});
+
+const booleanFieldSchema = baseFieldSchema.extend({
+  type: z.literal("boolean"),
+  default: z.boolean().optional(),
+});
+
+const selectFieldSchema = baseFieldSchema.extend({
+  type: z.literal("select"),
+  default: z.string().optional(),
+  options: z
+    .array(
+      z.object({
+        value: z.string().min(1).max(200),
+        labelKey: translationKeySchema,
+      }),
+    )
+    .min(1)
+    .max(50),
+});
+
+/**
+ * A credential: an API key, a token, a customer number the plugin signs in
+ * with (ADR 0037).
+ *
+ * Write-only from the admin screen: the host never returns the value to the
+ * browser, only whether one is set, and the board replaces or clears it. It is
+ * stored encrypted, apart from the other values, and handed back in clear only
+ * by `host.settings.read()` on the server. No default, because a credential
+ * written in a published manifest is not a secret.
+ */
+const secretFieldSchema = baseFieldSchema.extend({
+  type: z.literal("secret"),
+  minLength: z.int().min(1).optional(),
+  maxLength: z.int().min(1).max(10_000).optional(),
+});
+
+export const pluginSettingsFieldSchema = z.discriminatedUnion("type", [
+  textFieldSchema,
+  numberFieldSchema,
+  booleanFieldSchema,
+  selectFieldSchema,
+  secretFieldSchema,
+]);
+
+export type PluginSettingsField = z.infer<typeof pluginSettingsFieldSchema>;
+
+/**
+ * Checks a field's bounds against each other and against its default.
+ *
+ * Done while the manifest is parsed rather than left to the validator, because
+ * neither of the two paths a default takes goes through the field's
+ * constraints. `.default(value)` short-circuits an absent value and returns it
+ * without applying anything downstream, and `defaultSettings` reads the
+ * declaration directly. A number field declaring `min: 10, default: 5` would
+ * otherwise hand the plugin a 5 it said it would never see, and
+ * `minLength: 10, maxLength: 2` would declare a field no submitted value can
+ * satisfy - both of which are the plugin's mistake to hear about at install
+ * time rather than the board's to discover at a save.
+ */
+function checkFieldConstraints(
+  field: PluginSettingsField,
+  index: number,
+  ctx: z.RefinementCtx,
+): void {
+  const reject = (message: string, key: string): void => {
+    ctx.addIssue({
+      code: "custom",
+      message,
+      path: ["fields", index, key],
+    });
+  };
+
+  switch (field.type) {
+    case "text": {
+      if (
+        field.minLength !== undefined &&
+        field.maxLength !== undefined &&
+        field.minLength > field.maxLength
+      ) {
+        reject("minLength must not be greater than maxLength", "minLength");
+      }
+      if (field.default === undefined) {
+        return;
+      }
+      if (
+        field.minLength !== undefined &&
+        field.default.length < field.minLength
+      ) {
+        reject("the default is shorter than minLength", "default");
+      }
+      if (
+        field.maxLength !== undefined &&
+        field.default.length > field.maxLength
+      ) {
+        reject("the default is longer than maxLength", "default");
+      }
+      return;
+    }
+    case "number": {
+      if (
+        field.min !== undefined &&
+        field.max !== undefined &&
+        field.min > field.max
+      ) {
+        reject("min must not be greater than max", "min");
+      }
+      if (field.default === undefined) {
+        return;
+      }
+      if (field.integer && !Number.isInteger(field.default)) {
+        reject("the default is not an integer", "default");
+      }
+      if (field.min !== undefined && field.default < field.min) {
+        reject("the default is below min", "default");
+      }
+      if (field.max !== undefined && field.default > field.max) {
+        reject("the default is above max", "default");
+      }
+      return;
+    }
+    case "select": {
+      if (
+        field.default !== undefined &&
+        !field.options.some((option) => option.value === field.default)
+      ) {
+        reject("the default is not one of the declared options", "default");
+      }
+      return;
+    }
+    case "secret": {
+      if (
+        field.minLength !== undefined &&
+        field.maxLength !== undefined &&
+        field.minLength > field.maxLength
+      ) {
+        reject("minLength must not be greater than maxLength", "minLength");
+      }
+      return;
+    }
+    case "boolean":
+      return;
+  }
+}
+
+export const pluginSettingsSchema = z
+  .object({
+    fields: z
+      .array(pluginSettingsFieldSchema)
+      .max(50)
+      .refine(
+        (fields) =>
+          new Set(fields.map((field) => field.key)).size === fields.length,
+        { message: "field keys must be unique" },
+      ),
+  })
+  .superRefine((declaration, ctx) => {
+    declaration.fields.forEach((field, index) => {
+      checkFieldConstraints(field, index, ctx);
+    });
+  });
+
+export type PluginSettingsSchema = z.infer<typeof pluginSettingsSchema>;
+
+export type PluginSettingsValues = Record<string, string | number | boolean>;
+
+/**
+ * The declaration without its secret fields: what the admin screen is given
+ * values for, and what the host validates the stored plain values against.
+ */
+export function withoutSecretFields(
+  schema: PluginSettingsSchema,
+): PluginSettingsSchema {
+  return {
+    fields: schema.fields.filter((field) => field.type !== "secret"),
+  };
+}
+
+/**
+ * The validator for one secret value, as it is written.
+ *
+ * The bounds the field declares, and never the empty string: a secret is
+ * cleared by saying so rather than by storing nothing as a value, so a
+ * plugin reading it is never handed "" where it expects a key.
+ */
+export function secretValueValidator(
+  field: Extract<PluginSettingsField, { type: "secret" }>,
+): z.ZodString {
+  let secret = z.string().min(Math.max(1, field.minLength ?? 1));
+  if (field.maxLength !== undefined) {
+    secret = secret.max(field.maxLength);
+  }
+  return secret;
+}
+
+/**
+ * Builds the validator for one settings declaration.
+ *
+ * Produced from the declaration rather than written by the plugin, so the
+ * form the host renders and the values the host stores can never disagree
+ * about what is acceptable. Unknown keys are stripped: a plugin that drops a
+ * setting in a new version must not leave the old value behind to be handed
+ * back to it as something it no longer understands.
+ *
+ * A secret field reads as a string, which is how `host.settings.read()` hands
+ * it to the plugin. What the admin screen writes it with is the host's own
+ * rule, since the screen never holds the value it would be validating.
+ */
+export function settingsValidator(
+  schema: PluginSettingsSchema,
+): z.ZodType<PluginSettingsValues> {
+  const shape: Record<string, z.ZodTypeAny> = {};
+
+  for (const field of schema.fields) {
+    shape[field.key] = fieldValidator(field);
+  }
+
+  return z.object(shape).strip() as unknown as z.ZodType<PluginSettingsValues>;
+}
+
+function fieldValidator(field: PluginSettingsField): z.ZodTypeAny {
+  switch (field.type) {
+    case "text": {
+      let text = z.string();
+      if (field.minLength !== undefined) {
+        text = text.min(field.minLength);
+      }
+      if (field.maxLength !== undefined) {
+        text = text.max(field.maxLength);
+      }
+      // A required text field rejects the empty string. Without this a form
+      // submitted with the field untouched would satisfy "required" with a
+      // value the plugin has to treat as missing anyway.
+      return optionality(field.required ? text.min(1) : text, field);
+    }
+    case "number": {
+      let number = field.integer ? z.number().int() : z.number();
+      if (field.min !== undefined) {
+        number = number.min(field.min);
+      }
+      if (field.max !== undefined) {
+        number = number.max(field.max);
+      }
+      return optionality(number, field);
+    }
+    case "boolean":
+      return optionality(z.boolean(), field);
+    case "select":
+      return optionality(
+        z.enum(field.options.map((option) => option.value)),
+        field,
+      );
+    case "secret":
+      return optionality(secretValueValidator(field), field);
+  }
+}
+
+/**
+ * Applies the declared default and, for an optional field, tolerates absence.
+ *
+ * A default makes the field satisfied whether or not it was submitted, which
+ * is why it is applied before the optional wrapper rather than after.
+ */
+function optionality(
+  validator: z.ZodTypeAny,
+  field: PluginSettingsField,
+): z.ZodTypeAny {
+  if ("default" in field && field.default !== undefined) {
+    return validator.default(field.default);
+  }
+  return field.required ? validator : validator.optional();
+}
+
+/** The values a fresh installation starts with, from the declared defaults. */
+export function defaultSettings(
+  schema: PluginSettingsSchema,
+): PluginSettingsValues {
+  const values: PluginSettingsValues = {};
+  for (const field of schema.fields) {
+    if ("default" in field && field.default !== undefined) {
+      values[field.key] = field.default;
+    }
+  }
+  return values;
+}

package/src/standard-schema.ts

@@ -0,0 +1,39 @@
+/**
+ * The Standard Schema interface, version 1, as this package needs it.
+ *
+ * Declared here rather than imported, for the reason the rest of this package
+ * declares its own types: what an action's input and output are validated by is
+ * the host's business, and naming a validator in the published contract would
+ * make every plugin author's build depend on the one the host happens to use
+ * today. A structural interface says what the host requires - something that can
+ * validate an unknown value and report issues - and any library implementing the
+ * standard satisfies it, zod included.
+ *
+ * It is a subset: the parts the registry actually calls. `validate` is the one
+ * that matters, and note that it RETURNS its issues rather than throwing, which
+ * is the difference between this and a validator's own `parse`.
+ *
+ * The full specification is at standardschema.dev.
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly "~standard": {
+    /** The version of the standard this schema implements. */
+    readonly version: 1;
+    /** The library that produced the schema, for diagnostics. */
+    readonly vendor: string;
+    readonly validate: (
+      value: unknown,
+    ) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    readonly types?:
+      { readonly input: Input; readonly output: Output } | undefined;
+  };
+}
+
+export type StandardSchemaResult<Output> =
+  | { readonly value: Output; readonly issues?: undefined }
+  | { readonly issues: readonly StandardSchemaIssue[] };
+
+export interface StandardSchemaIssue {
+  readonly message: string;
+  readonly path?: readonly (PropertyKey | { readonly key: PropertyKey })[];
+}