@openbrf/plugin-sdk 1.0.0 → 1.2.0

package/src/permissions.ts

@@ -1,3 +1,5 @@
+import type { ActionPersonalData } from "./actions.ts";
+
 /**
  * What a plugin may ask the host for.
  *
@@ -11,6 +13,12 @@
  *
  * No permission grants write access to the register in v0. A plugin that
  * needs to change resident data is a core feature request, not a plugin.
+ *
+ * A new value here is a new member of the catalog's permission list, and an
+ * instance that does not know it refuses the whole catalog index that carries
+ * it. The catalog therefore lists an entry asking for one of the content
+ * permissions below only in an index that older instances do not read: the
+ * version 2 index (ADR 0032).
  */
 export const PLUGIN_PERMISSIONS = [
   /**
@@ -44,6 +52,106 @@ export const PLUGIN_PERMISSIONS = [
   "sms:send",
   /** Register background workers and enqueue or schedule jobs. */
   "jobs:schedule",
+  /**
+   * The fee notification runs and their notices, and the charges to members,
+   * as the board's own documents state them, and the events that say one was
+   * issued, recorded, corrected or removed.
+   *
+   * Masked as the files the board hands over are, and further: the names on a
+   * notice whose household holds a person with protected personal data are
+   * withheld, as on the fee notice file, and a charge on such a person withholds
+   * who and where entirely, where the debiting list withholds only where. A
+   * plugin is further from the board than the economic manager is, and the
+   * address book's rule that a protected person never reaches a plugin holds
+   * here too. A personal identity number is never returned, and there is no
+   * payment state to return: core records none.
+   */
+  "finances:read",
+  /**
+   * Record that a fee notice or a charge was delivered: by which route, when,
+   * and under which reference the receiving system knows it. A receipt and
+   * never a paid flag. Separate from finances:read because it writes, and the
+   * board consents to a plugin that only reads the books knowing that it cannot
+   * add anything to them.
+   */
+  "finances:recordDelivery",
+  /**
+   * Add blocks to the association's website.
+   *
+   * What such a block renders is published to anybody who reads the page,
+   * account or not, which is why it is a permission the board consents to
+   * rather than something a manifest may simply declare. The host prints what
+   * the block renders through an allowlist of elements, so it is never a
+   * script, a stylesheet or a resource from another host - but the words in it
+   * are the plugin's to choose.
+   */
+  "site:blocks",
+  /**
+   * The association's published news items: the title, the body's text, when
+   * each was published and whether it is for the members or for anyone.
+   *
+   * Not a register permission. It reads what the board has already
+   * published, and never who wrote an item, a comment on it or who read it
+   * (ADR 0032). The text is the board's and may name somebody, which is why a
+   * plugin holding it declares `freeText`.
+   */
+  "news:read",
+  /**
+   * The published events and their occurrences, and the notice of every
+   * general meeting that has been called and not yet held.
+   *
+   * Never a sign-up, a roll-call, an attendance or a proxy: how many places
+   * are left at an occurrence is the most it says about who is coming. Like
+   * news:read, it reads the board's text and declares `freeText`.
+   */
+  "calendar:read",
+  /**
+   * The bookable resources the house offers, and when each is taken. Never by
+   * whom: no booker, no apartment, no booking's identifier, and two bookings
+   * that touch are one interval (ADR 0032).
+   */
+  "bookings:readAvailability",
+  /**
+   * A stored picture, by its id: one held for anyone or for the members, whose
+   * upload declared that it shows no identifiable person (ADR 0032).
+   *
+   * Never a document, never a household's or the board's file, and never a
+   * picture of people: a photograph of a person needs a publication consent,
+   * and the consent the core records is for the website, not for wherever a
+   * plugin puts the picture. A picture is still a photograph, which is why a
+   * plugin holding it declares `photograph`.
+   */
+  "media:read",
+  /**
+   * The association's addresses: the street and number of each entrance, and
+   * nothing about who lives at them. Not addressBook:read, which reads the
+   * apartments and the people in them.
+   */
+  "addresses:read",
+  /**
+   * Install and update themes on the instance (ADR 0046).
+   *
+   * A theme is data and passes the same install lint however it arrives, so
+   * this grants no way past the theme gate: what a board consents to is a
+   * plugin putting themes on the instance's theme screen, for an
+   * administrator to preview and activate there. Each install is made for a
+   * person in the web interface who may install themes, never by the plugin on
+   * its own.
+   */
+  "themes:install",
+  /**
+   * Hand a member list to the core for the board to review (ADR 0043).
+   *
+   * The one way a plugin brings data towards the register, and it writes
+   * nothing: the core holds the file as an import proposal on its own import
+   * screen, and a board member previews, decides and applies it there, or
+   * rejects it. It grants no read of the register and raises no route's
+   * capability floor, so the plugin learns nothing about what the file would
+   * do. It does hold the file, though, which can carry every personal identity
+   * number in the cooperative and rows about persons with protected personal
+   * data, so a manifest declaring it declares those categories too.
+   */
+  "addressBook:proposeImport",
 ] as const;
 
 export type PluginPermission = (typeof PLUGIN_PERMISSIONS)[number];
@@ -52,13 +160,79 @@ export function isPluginPermission(value: string): value is PluginPermission {
   return (PLUGIN_PERMISSIONS as readonly string[]).includes(value);
 }
 
+/**
+ * Whether a permission lets a plugin read the register, or the finances that
+ * carry the names of the people in it.
+ *
+ * Every permission is classified, and the record is typed against
+ * `PluginPermission`, so a permission added to the list above fails to compile
+ * until somebody has said which it is. That is the point of a classification
+ * over a list of the refused: the rules that keep a plugin with a device route
+ * or a website block away from the register (ADR 0006, ADR 0031) hold a new
+ * permission that reads it out unless somebody remembers to add it to each.
+ * `finances:recordDelivery` writes a receipt and returns no one's details, so
+ * it is not a read. The content permissions (`news:read`, `calendar:read`,
+ * `bookings:readAvailability`, `media:read`, `addresses:read`) read what the
+ * website publishes, never the register, so a plugin with a device route may
+ * hold them; the host withholds text that names a resident from such a plugin.
+ */
+export const PERMISSION_REGISTER_ACCESS = {
+  "addressBook:read": "reads",
+  "addressBook:readContact": "reads",
+  "mail:send": "none",
+  "sms:send": "none",
+  "jobs:schedule": "none",
+  "finances:read": "reads",
+  "finances:recordDelivery": "none",
+  "site:blocks": "none",
+  "themes:install": "none",
+  "news:read": "none",
+  "calendar:read": "none",
+  "bookings:readAvailability": "none",
+  "media:read": "none",
+  "addresses:read": "none",
+  // Reads nothing from the register, but holds the member list it proposes.
+  // The rules that keep a device route or a website block away from it name
+  // this permission alongside `readsRegister` (ADR 0043).
+  "addressBook:proposeImport": "none",
+} as const satisfies Record<PluginPermission, "reads" | "none">;
+
+/** The permissions that read the register, in the order of the list above. */
+export const REGISTER_READING_PERMISSIONS: readonly PluginPermission[] =
+  PLUGIN_PERMISSIONS.filter(
+    (permission) => PERMISSION_REGISTER_ACCESS[permission] === "reads",
+  );
+
+/** Whether any of the permissions a manifest asks for reads the register. */
+export function readsRegister(permissions: readonly string[]): boolean {
+  return permissions.some((permission) =>
+    (REGISTER_READING_PERMISSIONS as readonly string[]).includes(permission),
+  );
+}
+
 /**
  * Categories of personal data a plugin declares it will process.
  *
  * Shown on the consent screen before an install, and stored with the
- * installation as the snapshot the board agreed to. It is a declaration, not
+ * installation as the snapshot the board agreed to. Installing the plugin
+ * writes them into the association's record of processing activities (GDPR
+ * art. 30) as the categories that processing touches. It is a declaration, not
  * an enforcement point: what the plugin can actually reach follows from its
- * permissions above.
+ * permissions above and from the actions it is allowed to call.
+ *
+ * Not only the register. A plugin that dispatches core actions handles
+ * whatever those actions return: an assistant passing issue reports and
+ * minutes to a model provider handles free text, and one reading charges
+ * handles financial data. So the list is ACTION_PERSONAL_DATA, in its order.
+ *
+ * Two of them only one kind of plugin may declare. A personal identity number
+ * is never returned to a plugin, and a person with protected personal data
+ * (skyddade personuppgifter) never appears in one's reads at all, so for any
+ * other plugin a declaration naming either would describe something that
+ * cannot happen. A plugin that proposes an import carries the member list the
+ * other way, and that list can hold both (ADR 0043): the manifest refuses
+ * either category without `addressBook:proposeImport`, and requires both with
+ * it.
  */
 export const PLUGIN_PERSONAL_DATA_CATEGORIES = [
   /** Given and family name. */
@@ -69,7 +243,53 @@ export const PLUGIN_PERSONAL_DATA_CATEGORIES = [
   "residency",
   "email",
   "phone",
-] as const;
+  /** A postal address of the person's own, not the apartment's. */
+  "postalAddress",
+  /**
+   * Personal identity number (personnummer). Only with
+   * `addressBook:proposeImport`.
+   */
+  "personalIdentityNumber",
+  /** Sign-in credentials and sessions. */
+  "account",
+  /** Charges, debiting basis and what a person owes or has paid. */
+  "financial",
+  /**
+   * Health, an art. 9 special category. Declared by a plugin that handles text
+   * people wrote themselves, where it may be volunteered.
+   */
+  "health",
+  /** A photograph, whether or not anybody is recognisable in it. */
+  "photograph",
+  /** Text a person wrote themselves, which may name anybody. */
+  "freeText",
+  /** The audit log's record of who did what to whose data. */
+  "auditTrail",
+  /**
+   * Rows about a person with protected personal data (skyddade
+   * personuppgifter). Only with `addressBook:proposeImport`.
+   */
+  "protected",
+] as const satisfies readonly ActionPersonalData[];
+
+/**
+ * The personal data categories a plugin that proposes an import must declare,
+ * and the two no other plugin may.
+ */
+export const PROPOSE_IMPORT_PERSONAL_DATA = [
+  "name",
+  "apartment",
+  "residency",
+  "email",
+  "phone",
+  "personalIdentityNumber",
+  "protected",
+] as const satisfies readonly PluginPersonalDataCategory[];
+
+export const PROPOSE_IMPORT_ONLY_PERSONAL_DATA = [
+  "personalIdentityNumber",
+  "protected",
+] as const satisfies readonly PluginPersonalDataCategory[];
 
 export type PluginPersonalDataCategory =
   (typeof PLUGIN_PERSONAL_DATA_CATEGORIES)[number];

package/src/recipients.ts

@@ -0,0 +1,294 @@
+import { z } from "zod";
+
+import { localizedTextSchema } from "./localized-text.ts";
+import { PLUGIN_PERSONAL_DATA_CATEGORIES } from "./permissions.ts";
+
+/**
+ * Where a plugin connects to outside the instance (ADR 0037).
+ *
+ * Declared in the manifest, and repeated in the catalog entry, for the reason
+ * actions are: the board reads it on the install consent screen before anything
+ * has been downloaded, and it is what the screen's question about where the
+ * plugin sends personal data is answered from.
+ *
+ * A declaration rather than a fence. A backend plugin runs at full process
+ * privilege (ADR 0003), so nothing here stops one opening a connection it did
+ * not declare; the catalog's reading of the server bundle is what holds a
+ * listed plugin to it.
+ */
+
+/** The longest origin a recipient may name. */
+const RECIPIENT_ORIGIN_MAX_LENGTH = 200;
+
+/** How many recipients a plugin may declare. */
+const MAX_RECIPIENTS = 8;
+
+/** What the joined hosts separate them with. */
+const HOST_SEPARATOR = ", ";
+
+/**
+ * An `https` origin: the scheme, the host and a port only where it is not 443.
+ *
+ * Written as the WHATWG URL parser writes an origin, so one place has one
+ * spelling: `https://API.example.com:443/` and `https://api.example.com` are the
+ * same recipient, and only the second is accepted. No path, because the board
+ * consents to a party and not to one of its endpoints; no credentials, because
+ * a manifest is published; and nothing but `https`, because what crosses the
+ * connection is the association's data. The host is a name: not an IP literal
+ * or `localhost`, which name no party the board can recognise, and not a name
+ * with a trailing dot, which is the same host under a second spelling.
+ */
+export const recipientOriginSchema = z
+  .string()
+  .min(1)
+  .max(RECIPIENT_ORIGIN_MAX_LENGTH)
+  .refine(isCanonicalHttpsOrigin, {
+    error:
+      'must be an https origin as a browser writes it, such as "https://api.example.com": lowercase, with no path, no trailing slash, no port 443, and a host name that is not an IP address, localhost or written with a trailing dot',
+  });
+
+/**
+ * The parts of a WHATWG URL read here.
+ *
+ * Reached through `globalThis` rather than the DOM's or Node's types: this
+ * package is compiled with neither, because it is bundled into the browser as
+ * well as required by the server, and both have the same `URL`.
+ */
+interface ParsedUrl {
+  protocol: string;
+  username: string;
+  password: string;
+  host: string;
+  hostname: string;
+  origin: string;
+}
+
+const WhatwgUrl = (
+  globalThis as unknown as { URL: new (input: string) => ParsedUrl }
+).URL;
+
+function isCanonicalHttpsOrigin(value: string): boolean {
+  let parsed: ParsedUrl;
+  try {
+    parsed = new WhatwgUrl(value);
+  } catch {
+    return false;
+  }
+  return (
+    parsed.protocol === "https:" &&
+    parsed.username === "" &&
+    parsed.password === "" &&
+    parsed.origin === value &&
+    isNamedHost(parsed.hostname)
+  );
+}
+
+/**
+ * Whether a host is a registered-style name: not a trailing-dot spelling, an
+ * IPv6 literal, a dotted IPv4 address or `localhost`. The parser has already
+ * turned any other IPv4 spelling (`0x7f.1`, `2130706433`) into the dotted one.
+ */
+function isNamedHost(hostname: string): boolean {
+  return !(
+    hostname.endsWith(".") ||
+    hostname.startsWith("[") ||
+    /^\d+\.\d+\.\d+\.\d+$/.test(hostname) ||
+    hostname === "localhost" ||
+    hostname.endsWith(".localhost")
+  );
+}
+
+/** The host a recipient's origin names, which is what a board recognises. */
+export function recipientHost(origin: string): string {
+  return new WhatwgUrl(origin).host;
+}
+
+/**
+ * The hosts of the declared recipients that receive personal data, joined.
+ *
+ * The answer a declaration gives to who receives the data (GDPR art.
+ * 30(1)(d)): what the consent screen fills its recipient field with and what
+ * the record of processing activities lists. A recipient receiving none is a
+ * place the plugin connects to, not a recipient in the sense of art. 4(9), so
+ * it is left out; an empty string when none receives any.
+ */
+export function receivingHosts(
+  recipients: readonly Pick<PluginRecipient, "origin" | "personalData">[],
+): string {
+  return recipients
+    .filter((recipient) => recipient.personalData.length > 0)
+    .map((recipient) => recipientHost(recipient.origin))
+    .join(HOST_SEPARATOR);
+}
+
+/**
+ * The longest `receivingHosts` can be: every recipient the declaration may
+ * hold, each at the longest origin less its `https://`. A field the answer is
+ * written to has to take at least this, or a valid declaration fills in an
+ * answer the field then refuses.
+ */
+export const RECEIVING_HOSTS_MAX_LENGTH =
+  MAX_RECIPIENTS * (RECIPIENT_ORIGIN_MAX_LENGTH - "https://".length) +
+  (MAX_RECIPIENTS - 1) * HOST_SEPARATOR.length;
+
+export const pluginRecipientSchema = z.object({
+  /** Unique in the manifest. Lowercase letters, digits and single hyphens. */
+  id: z
+    .string()
+    .min(2)
+    .max(32)
+    .regex(
+      /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/,
+      "must be lowercase letters, digits and single hyphens, starting with a letter",
+    ),
+  origin: recipientOriginSchema,
+  /** What the plugin connects there for, in Swedish and English. */
+  purpose: localizedTextSchema,
+  /**
+   * The personal-data categories this recipient receives, from the plugin's
+   * own `personalData`. Empty for a connection that carries none, such as
+   * fetching a list of models or the day's exchange rates: it is declared all
+   * the same, because the board is shown every place the plugin connects to.
+   */
+  personalData: z.array(z.enum(PLUGIN_PERSONAL_DATA_CATEGORIES)).max(16),
+});
+
+export type PluginRecipient = z.infer<typeof pluginRecipientSchema>;
+
+/**
+ * The declared recipients over a given reading of one recipient.
+ *
+ * The manifest reads a recipient as `pluginRecipientSchema` does and the
+ * catalog index reads the same fields strictly, as it reads everything. Both
+ * keep the rules below, which is why the list is built here rather than
+ * written twice.
+ *
+ * An id appears once and an origin appears once. Two declarations of one id
+ * would leave the consent snapshot and the board's screen naming different
+ * things by it; two of one origin would let a plugin state a narrow purpose
+ * and a wide one for the same party, and a board reading the first would have
+ * consented to the second.
+ *
+ * Undefaulted, on the terms of `declaredActionsSchema`: a manifest and a
+ * catalog entry add `.default([])`, and the install request does not, so an
+ * echo that left the field out is not read as consent to none.
+ */
+export function declaredRecipientsSchema<
+  T extends z.ZodType<{ id: string; origin: string }>,
+>(recipient: T) {
+  return z
+    .array(recipient)
+    .max(MAX_RECIPIENTS)
+    .superRefine((recipients, ctx) => {
+      const ids = new Set<string>();
+      const origins = new Set<string>();
+      for (const [index, declared] of recipients.entries()) {
+        if (ids.has(declared.id)) {
+          ctx.addIssue({
+            code: "custom",
+            path: [index, "id"],
+            message: `two recipients are declared with the id "${declared.id}"`,
+          });
+        }
+        if (origins.has(declared.origin)) {
+          ctx.addIssue({
+            code: "custom",
+            path: [index, "origin"],
+            message: `two recipients are declared with the origin "${declared.origin}"`,
+          });
+        }
+        ids.add(declared.id);
+        origins.add(declared.origin);
+      }
+    });
+}
+
+export const pluginRecipientsSchema = declaredRecipientsSchema(
+  pluginRecipientSchema,
+);
+
+/**
+ * The canonical string a recipient is consented to and compared by.
+ *
+ * The id, the origin and the categories: what the plugin may reach and what
+ * goes there. The purpose is the plugin's words for it and is shown, not
+ * compared, so a republished version that rewords one is not refused for it.
+ */
+export function canonicalRecipient(
+  recipient: Pick<PluginRecipient, "id" | "origin" | "personalData">,
+): string {
+  return [
+    recipient.id,
+    recipient.origin,
+    [...recipient.personalData].sort().join("|"),
+  ].join(" ");
+}
+
+/**
+ * The declared recipients a consent given to `consented`, as
+ * `canonicalRecipient` wrote it, does not cover.
+ *
+ * A recipient is covered by a consented one with the same id and origin that
+ * received every category it now receives. Fewer categories are covered: the
+ * plugin's data reaching that party narrowed, and the board agreed to more.
+ * One more, a new id or an id moved to another origin is not.
+ */
+export function recipientsBeyondConsent<
+  T extends Pick<PluginRecipient, "id" | "origin" | "personalData">,
+>(declared: readonly T[], consented: readonly string[]): T[] {
+  const agreed = new Map<string, ReadonlySet<string>>();
+  for (const canonical of consented) {
+    // Neither an id nor a canonical origin has a space in it.
+    const [id, origin, categories = ""] = canonical.split(" ");
+    agreed.set(
+      `${id} ${origin}`,
+      new Set(categories === "" ? [] : categories.split("|")),
+    );
+  }
+  return declared.filter((recipient) => {
+    const categories = agreed.get(`${recipient.id} ${recipient.origin}`);
+    return (
+      categories === undefined ||
+      recipient.personalData.some((category) => !categories.has(category))
+    );
+  });
+}
+
+/** Whether two declarations name the same recipients, as multisets. */
+export function sameRecipientDeclaration(
+  left: readonly Pick<PluginRecipient, "id" | "origin" | "personalData">[],
+  right: readonly Pick<PluginRecipient, "id" | "origin" | "personalData">[],
+): boolean {
+  const a = left.map(canonicalRecipient).sort();
+  const b = right.map(canonicalRecipient).sort();
+  return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+
+/**
+ * The recipients' categories that are not among the ones the plugin declares
+ * it handles, as issues at the path of each.
+ *
+ * What a recipient receives is part of what the plugin handles. One naming a
+ * category the plugin does not declare would put it on the consent screen, and
+ * into the record of who receives what, without the record of processing
+ * activities hearing of it. The manifest and the catalog entry repeat the same
+ * two fields, so both refuse it with this rule.
+ */
+export function recipientCategoryIssues(
+  recipients: readonly Pick<PluginRecipient, "personalData">[],
+  handled: readonly string[],
+): { path: (string | number)[]; message: string }[] {
+  const declared = new Set<string>(handled);
+  return recipients.flatMap((recipient, index) =>
+    recipient.personalData.flatMap((category, at) =>
+      declared.has(category)
+        ? []
+        : [
+            {
+              path: ["recipients", index, "personalData", at],
+              message: `"${category}" is not among the plugin's own personalData; a recipient receives only what the plugin declares it handles`,
+            },
+          ],
+    ),
+  );
+}