@openbrf/plugin-sdk 1.2.0 → 1.4.0

package/src/manifest.ts

@@ -219,6 +219,99 @@ export const PLUGIN_VIEW_SECTIONS = [
 
 export type PluginViewSection = (typeof PLUGIN_VIEW_SECTIONS)[number];
 
+/**
+ * Text a plugin author writes in both languages the interface is offered in.
+ *
+ * Strict, as everything in the processing declaration is: a field the
+ * declaration does not define is refused rather than dropped, so a misspelled
+ * key cannot leave a row of the record of processing activities without the
+ * text its author meant to put there.
+ */
+const pluginLocalizedTextSchema = z.strictObject({
+  sv: z.string().trim().min(1).max(500),
+  en: z.string().trim().min(1).max(500),
+});
+
+/**
+ * The art. 6(1) bases a plugin may declare its processing on.
+ *
+ * Four of the six. Vital interests and public task are not bases a housing
+ * cooperative's plugin has any business with, and a declaration naming one
+ * would be a claim the board then has to correct rather than a statement it can
+ * publish.
+ */
+export const PLUGIN_LEGAL_BASES = [
+  "consent",
+  "contract",
+  "legalObligation",
+  "legitimateInterest",
+] as const;
+
+export type PluginLegalBasis = (typeof PLUGIN_LEGAL_BASES)[number];
+
+/** Whose personal data a plugin's processing concerns. */
+export const PLUGIN_DATA_SUBJECTS = ["members", "residents"] as const;
+
+export type PluginDataSubject = (typeof PLUGIN_DATA_SUBJECTS)[number];
+
+/**
+ * What a plugin's processing of personal data is for, on what basis, for how
+ * long, and about whom (ADR 0035).
+ *
+ * The install seeds the plugin's row in the record of processing activities
+ * from it, in the association's language, and the consent screen shows it
+ * before anything is downloaded. It grants nothing: what a plugin may read is
+ * its permissions.
+ */
+export const pluginProcessingSchema = z
+  .strictObject({
+    purpose: pluginLocalizedTextSchema,
+    legalBasis: z.enum(PLUGIN_LEGAL_BASES),
+    /** The interest relied on, which art. 13(1)(d) requires on the notice. */
+    legitimateInterest: pluginLocalizedTextSchema.optional(),
+    /** How long the data is kept and when it goes. */
+    retention: pluginLocalizedTextSchema,
+    dataSubjects: z
+      .array(z.enum(PLUGIN_DATA_SUBJECTS))
+      .min(1)
+      .max(PLUGIN_DATA_SUBJECTS.length)
+      .refine(
+        (subjects) => new Set(subjects).size === subjects.length,
+        "names a category of data subjects twice",
+      ),
+  })
+  .superRefine((processing, ctx) => {
+    /*
+     * Both ways. A processing on legitimate interest names the interest,
+     * because the privacy notice has to; one on another basis names none,
+     * because the row would then carry an interest for a processing that does
+     * not rest on one.
+     */
+    if (
+      processing.legalBasis === "legitimateInterest" &&
+      processing.legitimateInterest === undefined
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["legitimateInterest"],
+        message: "a processing on legitimate interest names the interest",
+      });
+    }
+    if (
+      processing.legalBasis !== "legitimateInterest" &&
+      processing.legitimateInterest !== undefined
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["legitimateInterest"],
+        message:
+          'only a processing on "legitimateInterest" names a legitimate interest',
+      });
+    }
+  });
+
+export type PluginProcessing = z.infer<typeof pluginProcessingSchema>;
+
 export const pluginViewSchema = z.object({
   /** Named export of the remote module, per Module Federation. */
   module: z.string().min(1).max(100).default("./View"),
@@ -348,6 +441,7 @@ export interface ExtensionDeclarations {
   readonly id: string;
   readonly permissions: readonly string[];
   readonly personalData: readonly string[];
+  readonly deviceRoutes?: readonly unknown[];
   readonly extensionPoints: readonly {
     readonly personalData: readonly string[];
   }[];
@@ -364,10 +458,16 @@ export interface ExtensionDeclarations {
  * One function for the manifest and the catalog entry, so an entry the loader
  * would refuse is never offered for consent.
  */
-export function extensionRuleIssues(
-  declaration: ExtensionDeclarations,
-): { path: (string | number)[]; message: string }[] {
-  const issues: { path: (string | number)[]; message: string }[] = [];
+export function extensionRuleIssues(declaration: ExtensionDeclarations): {
+  path: (string | number)[];
+  message: string;
+  rule?: PluginManifestRule;
+}[] {
+  const issues: {
+    path: (string | number)[];
+    message: string;
+    rule?: PluginManifestRule;
+  }[] = [];
   const own = new Set(declaration.personalData);
 
   /*
@@ -410,6 +510,22 @@ export function extensionRuleIssues(
           'a plugin that asks for "site:blocks" declares extension points that accept no personal data',
       });
     }
+    /*
+     * A device is a screen on a wall, and a device token reaches a plugin's
+     * routes. A point that accepted contact details would let it reach them
+     * through an addon, so a plugin with device routes declares none that does
+     * (ADR 0030, ADR 0031).
+     */
+    const contact = point.personalData.filter(
+      (category) => category === "email" || category === "phone",
+    );
+    if ((declaration.deviceRoutes ?? []).length > 0 && contact.length > 0) {
+      issues.push({
+        path: ["extensionPoints", index, "personalData"],
+        message: `a plugin that declares deviceRoutes declares no extension point that accepts ${contact.join(" or ")}: contact details have no business on a device`,
+        rule: "device-route-extension-point-contact",
+      });
+    }
   }
 
   for (const [index, extension] of declaration.extends.entries()) {
@@ -1011,6 +1127,16 @@ export const pluginManifestSchema = z
       .array(z.enum(PLUGIN_PERSONAL_DATA_CATEGORIES))
       .max(16)
       .default([]),
+    /**
+     * What the processing of that personal data is for (ADR 0035).
+     *
+     * Declared by a plugin that declares personal data, and by no other: a
+     * plugin with none has no row in the record of processing activities.
+     * Optional here, so a plugin published before the field existed keeps
+     * loading; the package check, and so the catalog, refuses a package that
+     * declares personal data without it.
+     */
+    processing: pluginProcessingSchema.optional(),
     settingsSchema: pluginSettingsSchema.optional(),
     /**
      * The plugin's own screen in the application, when it has one, at
@@ -1103,14 +1229,30 @@ export const pluginManifestSchema = z
     released: calendarDaySchema.optional(),
   })
   .superRefine((manifest, ctx) => {
-    for (const issue of extensionRuleIssues(manifest)) {
+    for (const { rule, ...issue } of extensionRuleIssues(manifest)) {
       ctx.addIssue({
         code: "custom",
-        path: issue.path,
-        message: issue.message,
+        ...issue,
+        ...(rule === undefined ? {} : { params: { rule } }),
       });
     }
 
+    /*
+     * A processing with no personal data in it would seed a row of the record
+     * of processing activities claiming the plugin processes somebody's data,
+     * which is the placeholder this declaration exists to remove.
+     */
+    if (
+      manifest.processing !== undefined &&
+      manifest.personalData.length === 0
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["processing"],
+        message:
+          "a plugin that declares no personal data declares no processing",
+      });
+    }
     /*
      * A licence sold with a year of updates covers the releases published in
      * that year, and a release that does not say when it was published cannot
@@ -1267,6 +1409,56 @@ export type PluginExtensionPointDeclaration = z.infer<
 export type PluginExtensionDeclaration = z.infer<typeof pluginExtensionSchema>;
 export type PluginDeviceRoute = z.infer<typeof pluginDeviceRouteSchema>;
 
+/**
+ * The problem with a declaration that names personal data and no processing,
+ * or null when there is none.
+ *
+ * Not part of the manifest schema, which the loader also reads: a plugin
+ * published before the field existed has to keep loading, and its row keeps
+ * the placeholder it was seeded with. The package check and version 2 of the
+ * catalog index refuse it, so nothing listed from now on lacks one.
+ */
+export function missingProcessingProblem(declaration: {
+  personalData: readonly string[];
+  processing?: PluginProcessing | undefined;
+}): string | null {
+  return declaration.personalData.length > 0 &&
+    declaration.processing === undefined
+    ? "a plugin that declares personal data declares its processing"
+    : null;
+}
+
+/**
+ * Whether these permissions read the address book: a plugin holding one
+ * processes the residents' personal data, whatever it declares.
+ */
+export function readsAddressBook(permissions: readonly string[]): boolean {
+  return (
+    permissions.includes("addressBook:read") ||
+    permissions.includes("addressBook:readContact")
+  );
+}
+
+/**
+ * The problem with a declaration that reads the address book and names no
+ * personal data, or null when there is none.
+ *
+ * Such a plugin would have no processing declaration and no row in the record
+ * of processing activities, so nobody could object to what it reads. Held
+ * where `missingProcessingProblem` is, and for the same reason not in the
+ * manifest schema: a plugin published before this rule keeps loading, and its
+ * install keeps a row (`readsAddressBook`).
+ */
+export function undeclaredPersonalDataProblem(declaration: {
+  permissions: readonly string[];
+  personalData: readonly string[];
+}): string | null {
+  return readsAddressBook(declaration.permissions) &&
+    declaration.personalData.length === 0
+    ? "a plugin that reads the address book declares the personal data it reads"
+    : null;
+}
+
 /**
  * Dependency fields npm installs at install time.
  *

package/src/package-check.ts

@@ -1,6 +1,8 @@
 import {
   dependencyNames,
   isEmptyDependencyField,
+  missingProcessingProblem,
+  undeclaredPersonalDataProblem,
   parsePluginPackage,
   RUNTIME_DEPENDENCY_FIELDS,
 } from "./manifest.ts";
@@ -183,6 +185,19 @@ export function pluginPackageProblems(
   problems.push(...dependencyProblems(packageJson));
 
   if (parsed.ok) {
+    const processing = missingProcessingProblem(parsed.value.openbrf);
+    if (processing !== null) {
+      problems.push(
+        `The manifest in package.json is invalid at openbrf.processing: ${processing}.`,
+      );
+    }
+    const personalData = undeclaredPersonalDataProblem(parsed.value.openbrf);
+    if (personalData !== null) {
+      problems.push(
+        `The manifest in package.json is invalid at openbrf.personalData: ${personalData}.`,
+      );
+    }
+
     const entries = parsed.value.openbrf.entry;
     const files = new Set(contents.files.map(normalizedPath));
     for (const [kind, declared] of [