@openbrf/plugin-sdk 1.0.0 → 1.4.0

package/dist/permissions.js

@@ -11,6 +11,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,17 +50,175 @@ 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",
 ];
 export function isPluginPermission(value) {
     return PLUGIN_PERMISSIONS.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",
+};
+/** The permissions that read the register, in the order of the list above. */
+export const REGISTER_READING_PERMISSIONS = 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) {
+    return permissions.some((permission) => REGISTER_READING_PERMISSIONS.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. */
@@ -65,5 +229,49 @@ export const PLUGIN_PERSONAL_DATA_CATEGORIES = [
     "residency",
     "email",
     "phone",
+    /** 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",
+];
+/**
+ * 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",
+];
+export const PROPOSE_IMPORT_ONLY_PERSONAL_DATA = [
+    "personalIdentityNumber",
+    "protected",
 ];
 //# sourceMappingURL=permissions.js.map

package/dist/permissions.js.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC;;;;;;;;;OASG;IACH,kBAAkB;IAClB;;;;;OAKG;IACH,yBAAyB;IACzB,+DAA+D;IAC/D,WAAW;IACX;;;;;;;OAOG;IACH,UAAU;IACV,gEAAgE;IAChE,eAAe;CACP,CAAC;AAIX,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAQ,kBAAwC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,6BAA6B;IAC7B,MAAM;IACN,4DAA4D;IAC5D,WAAW;IACX,sEAAsE;IACtE,WAAW;IACX,OAAO;IACP,OAAO;CACC,CAAC"}
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC;;;;;;;;;OASG;IACH,kBAAkB;IAClB;;;;;OAKG;IACH,yBAAyB;IACzB,+DAA+D;IAC/D,WAAW;IACX;;;;;;;OAOG;IACH,UAAU;IACV,gEAAgE;IAChE,eAAe;IACf;;;;;;;;;;;;;OAaG;IACH,eAAe;IACf;;;;;;OAMG;IACH,yBAAyB;IACzB;;;;;;;;;OASG;IACH,aAAa;IACb;;;;;;;;OAQG;IACH,WAAW;IACX;;;;;;;OAOG;IACH,eAAe;IACf;;;;OAIG;IACH,2BAA2B;IAC3B;;;;;;;;;OASG;IACH,YAAY;IACZ;;;;OAIG;IACH,gBAAgB;IAChB;;;;;;;;;OASG;IACH,gBAAgB;IAChB;;;;;;;;;;;OAWG;IACH,2BAA2B;CACnB,CAAC;AAIX,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAQ,kBAAwC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,kBAAkB,EAAE,OAAO;IAC3B,yBAAyB,EAAE,OAAO;IAClC,WAAW,EAAE,MAAM;IACnB,UAAU,EAAE,MAAM;IAClB,eAAe,EAAE,MAAM;IACvB,eAAe,EAAE,OAAO;IACxB,yBAAyB,EAAE,MAAM;IACjC,aAAa,EAAE,MAAM;IACrB,gBAAgB,EAAE,MAAM;IACxB,WAAW,EAAE,MAAM;IACnB,eAAe,EAAE,MAAM;IACvB,2BAA2B,EAAE,MAAM;IACnC,YAAY,EAAE,MAAM;IACpB,gBAAgB,EAAE,MAAM;IACxB,0EAA0E;IAC1E,0EAA0E;IAC1E,wDAAwD;IACxD,2BAA2B,EAAE,MAAM;CAC0B,CAAC;AAEhE,8EAA8E;AAC9E,MAAM,CAAC,MAAM,4BAA4B,GACvC,kBAAkB,CAAC,MAAM,CACvB,CAAC,UAAU,EAAE,EAAE,CAAC,0BAA0B,CAAC,UAAU,CAAC,KAAK,OAAO,CACnE,CAAC;AAEJ,6EAA6E;AAC7E,MAAM,UAAU,aAAa,CAAC,WAA8B;IAC1D,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CACpC,4BAAkD,CAAC,QAAQ,CAAC,UAAU,CAAC,CACzE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,6BAA6B;IAC7B,MAAM;IACN,4DAA4D;IAC5D,WAAW;IACX,sEAAsE;IACtE,WAAW;IACX,OAAO;IACP,OAAO;IACP,iEAAiE;IACjE,eAAe;IACf;;;OAGG;IACH,wBAAwB;IACxB,wCAAwC;IACxC,SAAS;IACT,kEAAkE;IAClE,WAAW;IACX;;;OAGG;IACH,QAAQ;IACR,kEAAkE;IAClE,YAAY;IACZ,8DAA8D;IAC9D,UAAU;IACV,4DAA4D;IAC5D,YAAY;IACZ;;;OAGG;IACH,WAAW;CACqC,CAAC;AAEnD;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,MAAM;IACN,WAAW;IACX,WAAW;IACX,OAAO;IACP,OAAO;IACP,wBAAwB;IACxB,WAAW;CAC6C,CAAC;AAE3D,MAAM,CAAC,MAAM,iCAAiC,GAAG;IAC/C,wBAAwB;IACxB,WAAW;CAC6C,CAAC"}

package/dist/recipients.d.ts

@@ -0,0 +1,139 @@
+import { z } from "zod";
+/**
+ * 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 declare const recipientOriginSchema: z.ZodString;
+/** The host a recipient's origin names, which is what a board recognises. */
+export declare function recipientHost(origin: string): string;
+/**
+ * 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 declare function receivingHosts(recipients: readonly Pick<PluginRecipient, "origin" | "personalData">[]): string;
+/**
+ * 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 declare const RECEIVING_HOSTS_MAX_LENGTH: number;
+export declare const pluginRecipientSchema: z.ZodObject<{
+    id: z.ZodString;
+    origin: z.ZodString;
+    purpose: z.ZodObject<{
+        sv: z.ZodString;
+        en: z.ZodString;
+    }, z.core.$strict>;
+    personalData: z.ZodArray<z.ZodEnum<{
+        account: "account";
+        apartment: "apartment";
+        auditTrail: "auditTrail";
+        email: "email";
+        financial: "financial";
+        freeText: "freeText";
+        health: "health";
+        name: "name";
+        personalIdentityNumber: "personalIdentityNumber";
+        phone: "phone";
+        photograph: "photograph";
+        postalAddress: "postalAddress";
+        protected: "protected";
+        residency: "residency";
+    }>>;
+}, z.core.$strip>;
+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 declare function declaredRecipientsSchema<T extends z.ZodType<{
+    id: string;
+    origin: string;
+}>>(recipient: T): z.ZodArray<T>;
+export declare const pluginRecipientsSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    origin: z.ZodString;
+    purpose: z.ZodObject<{
+        sv: z.ZodString;
+        en: z.ZodString;
+    }, z.core.$strict>;
+    personalData: z.ZodArray<z.ZodEnum<{
+        account: "account";
+        apartment: "apartment";
+        auditTrail: "auditTrail";
+        email: "email";
+        financial: "financial";
+        freeText: "freeText";
+        health: "health";
+        name: "name";
+        personalIdentityNumber: "personalIdentityNumber";
+        phone: "phone";
+        photograph: "photograph";
+        postalAddress: "postalAddress";
+        protected: "protected";
+        residency: "residency";
+    }>>;
+}, z.core.$strip>>;
+/**
+ * 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 declare function canonicalRecipient(recipient: Pick<PluginRecipient, "id" | "origin" | "personalData">): string;
+/**
+ * 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 declare function recipientsBeyondConsent<T extends Pick<PluginRecipient, "id" | "origin" | "personalData">>(declared: readonly T[], consented: readonly string[]): T[];
+/** Whether two declarations name the same recipients, as multisets. */
+export declare function sameRecipientDeclaration(left: readonly Pick<PluginRecipient, "id" | "origin" | "personalData">[], right: readonly Pick<PluginRecipient, "id" | "origin" | "personalData">[]): boolean;
+/**
+ * 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 declare function recipientCategoryIssues(recipients: readonly Pick<PluginRecipient, "personalData">[], handled: readonly string[]): {
+    path: (string | number)[];
+    message: string;
+}[];
+//# sourceMappingURL=recipients.d.ts.map

package/dist/recipients.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipients.d.ts","sourceRoot":"","sources":["../src/recipients.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA4BxB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,aAO9B,CAAC;AAqDL,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,SAAS,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,cAAc,CAAC,EAAE,GACtE,MAAM,CAKR;AAED;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAEO,CAAC;AAE/C,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;iBAoBhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,EACnD,SAAS,EAAE,CAAC,iBA0Bb;AAED,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;kBAElC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,IAAI,CAAC,eAAe,EAAE,IAAI,GAAG,QAAQ,GAAG,cAAc,CAAC,GACjE,MAAM,CAMR;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,CAAC,SAAS,IAAI,CAAC,eAAe,EAAE,IAAI,GAAG,QAAQ,GAAG,cAAc,CAAC,EACjE,QAAQ,EAAE,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,EAAE,CAiB3D;AAED,uEAAuE;AACvE,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,SAAS,IAAI,CAAC,eAAe,EAAE,IAAI,GAAG,QAAQ,GAAG,cAAc,CAAC,EAAE,EACxE,KAAK,EAAE,SAAS,IAAI,CAAC,eAAe,EAAE,IAAI,GAAG,QAAQ,GAAG,cAAc,CAAC,EAAE,GACxE,OAAO,CAIT;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,SAAS,IAAI,CAAC,eAAe,EAAE,cAAc,CAAC,EAAE,EAC5D,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB;IAAE,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,CAclD"}

package/dist/recipients.js

@@ -0,0 +1,223 @@
+import { z } from "zod";
+import { localizedTextSchema } from "./localized-text.js";
+import { PLUGIN_PERSONAL_DATA_CATEGORIES } from "./permissions.js";
+/**
+ * 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',
+});
+const WhatwgUrl = globalThis.URL;
+function isCanonicalHttpsOrigin(value) {
+    let parsed;
+    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) {
+    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) {
+    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) {
+    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),
+});
+/**
+ * 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(recipient) {
+    return z
+        .array(recipient)
+        .max(MAX_RECIPIENTS)
+        .superRefine((recipients, ctx) => {
+        const ids = new Set();
+        const origins = new Set();
+        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) {
+    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(declared, consented) {
+    const agreed = new Map();
+    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, right) {
+    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, handled) {
+    const declared = new Set(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`,
+            },
+        ]));
+}
+//# sourceMappingURL=recipients.js.map

package/dist/recipients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipients.js","sourceRoot":"","sources":["../src/recipients.ts"],"names":[],"mappings":"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"}