@openbrf/plugin-sdk 1.2.0 → 1.4.0

package/src/catalog.ts

@@ -5,6 +5,8 @@ import { IntegrityError, parseSha512 } from "./integrity.ts";
 import { localizedTextSchema } from "./localized-text.ts";
 import {
   declaredActionsSchema,
+  missingProcessingProblem,
+  undeclaredPersonalDataProblem,
   declaredExtensionPointsSchema,
   declaredExtensionsSchema,
   extensionGroupRefusals,
@@ -21,6 +23,7 @@ import {
   pluginDeviceRouteSchema,
   pluginIdSchema,
   pluginManifestSchema,
+  pluginProcessingSchema,
   proposeImportPersonalDataIssues,
 } from "./manifest.ts";
 import {
@@ -57,6 +60,12 @@ import {
  * any check of the manifest saw it. The index carries its version for exactly
  * this, so a new field is a new index version rather than a key an older
  * instance ignores.
+ *
+ * An instance reads both versions there are. Version 2 adds the device routes
+ * of ADR 0031 and the processing declaration of ADR 0035 to a plugin entry, and
+ * the other fields of ADR 0030 join them there as they are built; version 1 is
+ * the index as it stood before, which a catalog keeps serving to instances that
+ * read nothing newer.
  */
 
 /** Whether `declared` is a digest `parseSha512` can read. */
@@ -275,6 +284,20 @@ export const catalogPluginEntrySchema = baseEntrySchema
     }
   });
 
+/**
+ * A plugin entry in version 2 of the index: version 1's, and the processing
+ * declaration.
+ *
+ * Repeated from the manifest on the terms the permissions are, because the
+ * consent screen shows it before anything is downloaded and the install seeds
+ * the record of processing activities from what that screen showed. Whether it
+ * is there is decided with the personal data, by the index as a whole below,
+ * since a refined object cannot be extended into the next version's entry.
+ */
+export const catalogPluginEntryV2Schema = catalogPluginEntrySchema.extend({
+  processing: pluginProcessingSchema.optional(),
+});
+
 /**
  * A theme entry. Themes install through the same download-and-verify path and
  * are listed in the same index; what happens after the bytes are verified is
@@ -296,27 +319,181 @@ export const catalogEntrySchema = z.discriminatedUnion("type", [
   catalogThemeEntrySchema,
 ]);
 
-export type CatalogPluginEntry = z.infer<typeof catalogPluginEntrySchema>;
-export type CatalogThemeEntry = z.infer<typeof catalogThemeEntrySchema>;
-export type CatalogEntry = z.infer<typeof catalogEntrySchema>;
+export const catalogEntryV2Schema = z.discriminatedUnion("type", [
+  catalogPluginEntryV2Schema,
+  catalogThemeEntrySchema,
+]);
 
 /**
- * The index versions this package reads.
- *
- * Version 2 adds the fields ADR 0030 lists: `extensionPoints` and `extends`
- * (ADR 0030), `recipients` (ADR 0037) and `deviceRoutes` (ADR 0031). An
- * instance reads both, and the catalog serves version 1, without the entries
- * that need version 2, to instances that have not upgraded.
+ * A plugin entry, as whichever version of the index it came from. A version 1
+ * entry is one with no processing and no device routes declared.
  */
-export const CATALOG_INDEX_VERSIONS = [1, 2] as const;
+export type CatalogPluginEntry = z.infer<typeof catalogPluginEntryV2Schema>;
+export type CatalogThemeEntry = z.infer<typeof catalogThemeEntrySchema>;
+export type CatalogEntry = CatalogPluginEntry | CatalogThemeEntry;
+
+/** The index's rules about its entries taken together, in either version. */
+function checkEntries(
+  catalog: { version: 1 | 2; entries: readonly CatalogEntry[] },
+  ctx: z.RefinementCtx,
+): void {
+  for (const [index, entry] of catalog.entries.entries()) {
+    if (entry.type !== "plugin") {
+      continue;
+    }
+    // The manifest's rule, so an entry the loader would refuse is never
+    // offered for consent.
+    for (const issue of proposeImportPersonalDataIssues(entry)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["entries", index, "personalData"],
+        message: issue.message,
+      });
+    }
+  }
 
-export const catalogSchema = z
+  for (const [index, entry] of catalog.entries.entries()) {
+    if (entry.type !== "plugin") {
+      continue;
+    }
+    /*
+     * A field version 1 does not define is refused there as any unknown key
+     * is, so an older instance and this one read the same index the same
+     * way.
+     */
+    if (catalog.version === 1) {
+      for (const field of [
+        "extensionPoints",
+        "extends",
+        "deviceRoutes",
+      ] as const) {
+        if (entry[field] !== undefined) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["entries", index, field],
+            message: `${field} needs version 2 of the index`,
+          });
+        }
+      }
+      continue;
+    }
+    // The manifest's own rules, so an entry whose own declaration breaks
+    // one is never offered for consent.
+    for (const issue of extensionRuleIssues({
+      id: entry.id,
+      permissions: entry.permissions,
+      personalData: entry.personalData,
+      deviceRoutes: entry.deviceRoutes ?? [],
+      extensionPoints: entry.extensionPoints ?? [],
+      extends: entry.extends ?? [],
+    })) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["entries", index, ...issue.path],
+        message: issue.message,
+      });
+    }
+    // The manifest's own rules, so an entry that the loader would refuse is
+    // never offered for consent.
+    for (const issue of deviceRouteRuleIssues({
+      deviceRoutes: entry.deviceRoutes ?? [],
+      oauthProtectedResource: entry.oauthProtectedResource,
+      permissions: entry.permissions,
+    })) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["entries", index, ...issue.path],
+        message: issue.message,
+      });
+    }
+  }
+
+  /*
+   * A field is in the version that defines it and in no earlier one: an
+   * instance that reads only version 1 would refuse the entry, and an index
+   * claiming version 1 while carrying it is not one such an instance could
+   * read.
+   */
+  if (catalog.version === 1) {
+    for (const [index, entry] of catalog.entries.entries()) {
+      if (entry.type === "plugin" && entry.recipients !== undefined) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["entries", index, "recipients"],
+          message:
+            "recipients is not in version 1 of the index; an entry that declares them is listed in version 2",
+        });
+      }
+    }
+  }
+
+  /*
+   * The manifest's rule on what a recipient may receive, so an entry the
+   * loader would refuse is not offered for consent with a category the
+   * plugin does not declare it handles. The comparison with the installed
+   * manifest comes later; this holds the entry to itself.
+   */
+  for (const [index, entry] of catalog.entries.entries()) {
+    if (entry.type !== "plugin" || entry.recipients === undefined) {
+      continue;
+    }
+    for (const issue of recipientCategoryIssues(
+      entry.recipients,
+      entry.personalData,
+    )) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["entries", index, ...issue.path],
+        message: issue.message,
+      });
+    }
+  }
+
+  /*
+   * An id names one entry in the whole index, not one per type. An install
+   * finds its entry by id and then refuses one of the wrong type, so a theme
+   * sharing a plugin's id would leave that plugin impossible to install, and
+   * which of the two a board got would depend on the order of the file.
+   */
+  const firstIndexById = new Map<string, number>();
+  for (const [index, entry] of catalog.entries.entries()) {
+    const first = firstIndexById.get(entry.id);
+    if (first === undefined) {
+      firstIndexById.set(entry.id, index);
+      continue;
+    }
+    ctx.addIssue({
+      code: "custom",
+      path: ["entries", index, "id"],
+      message: `"${entry.id}" is already the id of entry ${String(first)}; an id appears once in the index`,
+    });
+  }
+}
+
+const catalogV1Schema = z
   .strictObject({
     /** Index format version, so a future shape can be recognised and refused. */
-    version: z.literal(CATALOG_INDEX_VERSIONS),
+    version: z.literal(1),
     entries: z.array(catalogEntrySchema).max(500),
   })
   .superRefine((catalog, ctx) => {
+    checkEntries(catalog, ctx);
+  });
+
+const catalogV2Schema = z
+  .strictObject({
+    /**
+     * Version 2 adds the fields `CATALOG_INDEX_VERSIONS` lists to a plugin
+     * entry, `processing` (ADR 0035) among them, and changes nothing else.
+     * This package reads both versions; the catalog keeps serving version 1,
+     * without the entries that need version 2, to instances that have not
+     * upgraded.
+     */
+    version: z.literal(2),
+    entries: z.array(catalogEntryV2Schema).max(500),
+  })
+  .superRefine((catalog, ctx) => {
+    checkEntries(catalog, ctx);
     const plugins = new Map<string, CatalogPluginEntry>();
     const pluginIndex = new Map<string, number>();
     for (const [index, entry] of catalog.entries.entries()) {
@@ -327,64 +504,40 @@ export const catalogSchema = z
     }
     /** The addons already refused beside a plugin they extend. */
     const pairRefused = new Set<string>();
+    /*
+     * The manifest's own rule, both ways: an entry that declares personal data
+     * declares its processing, and one that declares none declares no
+     * processing. One that reads the address book declares personal data, so
+     * it has a processing a person can object to. Held here rather than only
+     * by the catalog's check of the package, so an index written by hand is
+     * held to it as well.
+     */
     for (const [index, entry] of catalog.entries.entries()) {
       if (entry.type !== "plugin") {
         continue;
       }
-      // The manifest's rule, so an entry the loader would refuse is never
-      // offered for consent.
-      for (const issue of proposeImportPersonalDataIssues(entry)) {
+      const missing = missingProcessingProblem(entry);
+      if (missing !== null) {
         ctx.addIssue({
           code: "custom",
-          path: ["entries", index, "personalData"],
-          message: issue.message,
+          path: ["entries", index, "processing"],
+          message: missing,
         });
       }
-      /*
-       * A field version 1 does not define is refused there as any unknown key
-       * is, so an older instance and this one read the same index the same
-       * way.
-       */
-      if (catalog.version === 1) {
-        for (const field of [
-          "extensionPoints",
-          "extends",
-          "deviceRoutes",
-        ] as const) {
-          if (entry[field] !== undefined) {
-            ctx.addIssue({
-              code: "custom",
-              path: ["entries", index, field],
-              message: `${field} needs version 2 of the index`,
-            });
-          }
-        }
-        continue;
-      }
-      // The manifest's own rules, so an entry whose own declaration breaks
-      // one is never offered for consent.
-      for (const issue of extensionRuleIssues({
-        id: entry.id,
-        permissions: entry.permissions,
-        personalData: entry.personalData,
-        extensionPoints: entry.extensionPoints ?? [],
-        extends: entry.extends ?? [],
-      })) {
+      const undeclared = undeclaredPersonalDataProblem(entry);
+      if (undeclared !== null) {
         ctx.addIssue({
           code: "custom",
-          path: ["entries", index, ...issue.path],
-          message: issue.message,
+          path: ["entries", index, "personalData"],
+          message: undeclared,
         });
       }
-      for (const issue of deviceRouteRuleIssues({
-        deviceRoutes: entry.deviceRoutes ?? [],
-        oauthProtectedResource: entry.oauthProtectedResource,
-        permissions: entry.permissions,
-      })) {
+      if (entry.processing !== undefined && entry.personalData.length === 0) {
         ctx.addIssue({
           code: "custom",
-          path: ["entries", index, ...issue.path],
-          message: issue.message,
+          path: ["entries", index, "processing"],
+          message:
+            "a plugin that declares no personal data declares no processing",
         });
       }
       /*
@@ -490,70 +643,32 @@ export const catalogSchema = z
         });
       }
     }
+  });
 
-    /*
-     * A field is in the version that defines it and in no earlier one: an
-     * instance that reads only version 1 would refuse the entry, and an index
-     * claiming version 1 while carrying it is not one such an instance could
-     * read.
-     */
-    if (catalog.version === 1) {
-      for (const [index, entry] of catalog.entries.entries()) {
-        if (entry.type === "plugin" && entry.recipients !== undefined) {
-          ctx.addIssue({
-            code: "custom",
-            path: ["entries", index, "recipients"],
-            message:
-              "recipients is not in version 1 of the index; an entry that declares them is listed in version 2",
-          });
-        }
-      }
-    }
+/**
+ * The index versions this package reads.
+ *
+ * Version 2 adds the fields ADR 0030 lists: `extensionPoints` and `extends`
+ * (ADR 0030), `recipients` (ADR 0037) and `deviceRoutes` (ADR 0031), and
+ * `processing` (ADR 0035). An instance reads both, and the catalog serves
+ * version 1, without the entries that need version 2, to instances that have
+ * not upgraded.
+ */
+export const CATALOG_INDEX_VERSIONS = [1, 2] as const;
 
-    /*
-     * The manifest's rule on what a recipient may receive, so an entry the
-     * loader would refuse is not offered for consent with a category the
-     * plugin does not declare it handles. The comparison with the installed
-     * manifest comes later; this holds the entry to itself.
-     */
-    for (const [index, entry] of catalog.entries.entries()) {
-      if (entry.type !== "plugin" || entry.recipients === undefined) {
-        continue;
-      }
-      for (const issue of recipientCategoryIssues(
-        entry.recipients,
-        entry.personalData,
-      )) {
-        ctx.addIssue({
-          code: "custom",
-          path: ["entries", index, ...issue.path],
-          message: issue.message,
-        });
-      }
-    }
+/** The version of the index this SDK writes and reads first. */
+export const CATALOG_INDEX_VERSION = 2;
 
-    /*
-     * An id names one entry in the whole index, not one per type. An install
-     * finds its entry by id and then refuses one of the wrong type, so a theme
-     * sharing a plugin's id would leave that plugin impossible to install, and
-     * which of the two a board got would depend on the order of the file.
-     */
-    const firstIndexById = new Map<string, number>();
-    for (const [index, entry] of catalog.entries.entries()) {
-      const first = firstIndexById.get(entry.id);
-      if (first === undefined) {
-        firstIndexById.set(entry.id, index);
-        continue;
-      }
-      ctx.addIssue({
-        code: "custom",
-        path: ["entries", index, "id"],
-        message: `"${entry.id}" is already the id of entry ${String(first)}; an id appears once in the index`,
-      });
-    }
-  });
+export const catalogSchema = z.discriminatedUnion("version", [
+  catalogV1Schema,
+  catalogV2Schema,
+]);
 
-export type Catalog = z.infer<typeof catalogSchema>;
+/** An index of either version, read as one shape. */
+export interface Catalog {
+  version: z.infer<typeof catalogSchema>["version"];
+  entries: CatalogEntry[];
+}
 
 /**
  * The refusals of an index that its reader is told in their own language.

package/src/findings.ts

@@ -158,6 +158,8 @@ export const PLUGIN_MANIFEST_RULES = [
   "device-route-proposes-import",
   /** A plugin with a website block also proposes imports. */
   "blocks-propose-import",
+  /** A plugin with a device route offers an extension point accepting contact details. */
+  "device-route-extension-point-contact",
 ] as const;
 
 export type PluginManifestRule = (typeof PLUGIN_MANIFEST_RULES)[number];

package/src/host.ts

@@ -174,6 +174,12 @@ export interface PluginApartment {
 export interface PluginResident {
   personId: string;
   name: string;
+  /**
+   * The family name alone, for a reader that shows no first names: a household
+   * as the name on the door shows it, without the first names that say who
+   * lives alone and name the children.
+   */
+  lastName: string;
   /** MEMBER holds the tenant-ownership; RESIDENT occupies without holding it. */
   role: "MEMBER" | "RESIDENT";
   apartment: PluginApartment | null;
@@ -183,6 +189,22 @@ export interface PluginResident {
   email?: string | null;
   /** Present only with the addressBook:readContact permission. */
   phone?: string | null;
+  /**
+   * Whether a publication consent to the person's name on screens inside the
+   * building stands (the `NAME_IN_BUILDING` scope), recorded by the board on
+   * the person's panel like every other scope. A different consent from a name
+   * on the website, because the two are different things to agree to.
+   */
+  nameInBuilding: boolean;
+}
+
+/** Narrows a read of the residents. */
+export interface PluginResidentFilter {
+  /**
+   * Only the residents of this entrance, so a plugin that shows one entrance
+   * never loads the others. An id no address has returns nobody.
+   */
+  addressId?: string;
 }
 
 export interface PluginOccupancySummary {
@@ -202,14 +224,76 @@ export interface PluginOccupancySummary {
  * personal identity number is never returned, and nothing is writable.
  * Requires addressBook:read; the contact fields additionally require
  * addressBook:readContact.
+ *
+ * A person who has objected to this plugin's processing, and whose objection
+ * the board granted, is absent as well (ADR 0035) - absent, not flagged, so a
+ * plugin cannot list who objected. Closing the objection brings the person
+ * back on the next read.
  */
 export interface PluginAddressBook {
   apartments(): Promise<PluginApartment[]>;
-  /** Current residencies only. Moved-out rows are not plugin business. */
-  residents(): Promise<PluginResident[]>;
+  /**
+   * Current residencies only. Moved-out rows are not plugin business.
+   *
+   * The filter was added after this contract version shipped; an older host
+   * ignores it and returns every entrance, so a plugin that must not load the
+   * others filters the result by `apartment.address.id` as well.
+   */
+  residents(filter?: PluginResidentFilter): Promise<PluginResident[]>;
   summary(): Promise<PluginOccupancySummary>;
 }
 
+/** The bounds `host.audit.record` holds an entry to. */
+export const PLUGIN_AUDIT_LIMITS = {
+  /** Characters in `event`, which is also part of a text key. */
+  event: 64,
+  /** Characters in `targetKind`. */
+  targetKind: 64,
+  /** Characters in `targetId`. */
+  targetId: 200,
+  /** Values in `detail`. */
+  detailValues: 8,
+  /** Characters in a key of `detail`, letters and digits. */
+  detailKey: 64,
+  /** Characters in a string value of `detail`. */
+  detailValue: 200,
+} as const;
+
+/** One entry a plugin writes to the instance's audit log. */
+export interface PluginAuditEntry {
+  /**
+   * What happened, as lowercase letters, digits, dots and hyphens, starting
+   * with a letter: `screen.residents-enabled`. The audit log shows it through
+   * the plugin's own text key `audit.<event>`.
+   */
+  event: string;
+  /** What the act was done to, in the plugin's own words: `screen`. */
+  targetKind?: string;
+  /** Which one: the screen's id. */
+  targetId?: string;
+  /**
+   * At most eight values about the act, never a copy of what the plugin read.
+   * A key is letters and digits, starting with a letter: `screenCount`. A
+   * person is named as the actor, never here, and a key or value holding a
+   * personal identity number is refused.
+   */
+  detail?: Record<string, string | number | boolean>;
+}
+
+/**
+ * Writing to the instance's audit log (ADR 0035).
+ *
+ * The entry is written as `PLUGIN_RECORDED`, with the plugin's id and the
+ * event, on the plugin channel. With a request, the actor is the person the
+ * host marked on it, as for `actions`; with `null`, the entry has no actor - a
+ * plugin's own job, say. An entry that breaks a bound is refused with a
+ * RangeError and nothing is written. Needs no permission: an entry is about
+ * what the plugin did, which the association is entitled to a record of.
+ */
+export interface PluginAudit {
+  record(request: ActionRequest | null, entry: PluginAuditEntry): Promise<void>;
+}
+
 /** What a theme install is told about the package besides its bytes. */
 export interface PluginThemeInstallOptions {
   /**
@@ -306,6 +390,13 @@ export interface PluginNewsItem {
   readonly audience: PluginContentAudience;
   /** ISO 8601 instant. */
   readonly publishedAt: string;
+  /**
+   * Whether the board marked the item "show on screens": that it may be shown
+   * on a screen in the building (ADR 0050). Off until the board sets it. A
+   * plugin that puts items where anybody passing can read them shows only the
+   * marked ones.
+   */
+  readonly onScreens: boolean;
 }
 
 /**
@@ -358,6 +449,11 @@ export interface PluginOccurrence {
    */
   readonly placesLeft: number | null;
   readonly audience: PluginContentAudience;
+  /**
+   * Whether the board marked the event, with all its occurrences, "show on
+   * screens" (ADR 0050), as a news item's mark.
+   */
+  readonly onScreens: boolean;
 }
 
 /**
@@ -508,6 +604,12 @@ export interface PluginMediaFile {
    * picture's entity tag from, so a plugin may use it as one too.
    */
   readonly checksum: string;
+  /**
+   * Who the picture is for: `anyone`, or the `members`, as the board held it.
+   * The host does not filter for you, because it cannot know where you put it;
+   * see {@link PluginContentAudience}.
+   */
+  readonly audience: PluginContentAudience;
   /**
    * The picture's bytes. Read it to the end or cancel it: the host holds the
    * stored file open until one or the other.
@@ -799,6 +901,14 @@ export interface PluginHost {
    * before using it.
    */
   blocks: PluginBlocks;
+  /**
+   * The instance's audit log, for what this plugin did.
+   *
+   * Added after this contract version shipped, like `actions`: a plugin built
+   * against a newer host than the one it is installed on must feature-detect
+   * before using it.
+   */
+  audit: PluginAudit;
   /**
    * The extension points this plugin offers or extends (ADR 0030): a host
    * plugin defines its points and calls the addons serving there, and an

package/src/index.ts

@@ -83,11 +83,14 @@ export {
   type CatalogDiagnostic,
   type CatalogEntry,
   catalogEntrySchema,
+  catalogEntryV2Schema,
+  CATALOG_INDEX_VERSION,
   type CatalogExtensionPoint,
   catalogExtensionPointSchema,
   type CatalogParseResult,
   type CatalogPluginEntry,
   catalogPluginEntrySchema,
+  catalogPluginEntryV2Schema,
   type CatalogRefusal,
   type CatalogRefusalCode,
   catalogSchema,
@@ -170,6 +173,9 @@ export {
   type PluginAddressBook,
   type PluginAddresses,
   type PluginApartment,
+  type PluginAudit,
+  type PluginAuditEntry,
+  PLUGIN_AUDIT_LIMITS,
   type PluginBookableResource,
   type PluginBookings,
   type PluginBusyInterval,
@@ -198,6 +204,7 @@ export {
   type PluginRecipientResponse,
   type PluginRecipients,
   type PluginResident,
+  type PluginResidentFilter,
   type PluginSettings,
   type PluginInstalledTheme,
   type PluginSms,
@@ -227,6 +234,11 @@ export {
   licenceKeyIdSchema,
   licencePublicKeySchema,
   type ManifestParseResult,
+  missingProcessingProblem,
+  readsAddressBook,
+  undeclaredPersonalDataProblem,
+  PLUGIN_DATA_SUBJECTS,
+  PLUGIN_LEGAL_BASES,
   type PluginActionDeclaration,
   pluginActionSchema,
   pluginActionsSchema,
@@ -240,12 +252,16 @@ export {
   pluginExtensionPointSchema,
   pluginExtensionSchema,
   pluginIdSchema,
+  type PluginDataSubject,
+  type PluginLegalBasis,
   type PluginLicenceDeclaration,
   pluginLicenceSchema,
   type PluginManifest,
   pluginManifestSchema,
   type PluginPackage,
   pluginPackageSchema,
+  type PluginProcessing,
+  pluginProcessingSchema,
   type PluginView,
   pluginViewSchema,
   type PluginViewSection,