@openbrf/plugin-sdk 1.0.0 → 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

@@ -68,11 +68,28 @@ const selectFieldSchema = baseFieldSchema.extend({
     .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>;
@@ -160,6 +177,16 @@ function checkFieldConstraints(
       }
       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;
   }
@@ -186,6 +213,35 @@ 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.
  *
@@ -194,6 +250,10 @@ export type PluginSettingsValues = Record<string, string | number | boolean>;
  * 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,
@@ -239,6 +299,8 @@ function fieldValidator(field: PluginSettingsField): z.ZodTypeAny {
         z.enum(field.options.map((option) => option.value)),
         field,
       );
+    case "secret":
+      return optionality(secretValueValidator(field), field);
   }
 }
 
@@ -252,7 +314,7 @@ function optionality(
   validator: z.ZodTypeAny,
   field: PluginSettingsField,
 ): z.ZodTypeAny {
-  if (field.default !== undefined) {
+  if ("default" in field && field.default !== undefined) {
     return validator.default(field.default);
   }
   return field.required ? validator : validator.optional();
@@ -264,7 +326,7 @@ export function defaultSettings(
 ): PluginSettingsValues {
   const values: PluginSettingsValues = {};
   for (const field of schema.fields) {
-    if (field.default !== undefined) {
+    if ("default" in field && field.default !== undefined) {
       values[field.key] = field.default;
     }
   }