@skillcdn/console 0.4.4 → 0.4.5

package/src/plugin/bridge.ts

@@ -160,6 +160,17 @@ export interface BridgeDownload {
   readonly id: string;
 }
 
+/**
+ * A link a person pressed in the frame, for the console's page to open in a new tab (ADR-0067):
+ * the frame's sandbox opens no window itself, and the page opens one only for a web or a mail
+ * address, and only right after a person pressed.
+ */
+export interface BridgeOpen {
+  readonly v: 1;
+  readonly t: "open";
+  readonly url: string;
+}
+
 export interface BridgeSubscribe {
   readonly v: 1;
   readonly t: "subscribe";
@@ -183,6 +194,7 @@ export type BridgeToPage =
   | BridgeResize
   | BridgeTitle
   | BridgeDownload
+  | BridgeOpen
   | BridgeSubscribe;
 
 /** A path of the console's, as `navigate` and `path` carry one: absolute, no scheme, no host, one line. */
@@ -212,6 +224,37 @@ export function isBridgePath(value: unknown): value is string {
   );
 }
 
+/** The schemes a link pressed in a frame may open in a new tab: the web, and mail. Nothing that runs. */
+const OPENABLE_SCHEMES: ReadonlySet<string> = new Set(["https:", "http:", "mailto:"]);
+export const MAX_BRIDGE_URL_LENGTH = 2048;
+
+/** True for an address the page may open in a new tab for a frame: an absolute web or mail address, one line. */
+export function isBridgeUrl(value: unknown): value is string {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > MAX_BRIDGE_URL_LENGTH ||
+    /\s/.test(value) ||
+    [...value].some((character) => {
+      const code = character.codePointAt(0) ?? 0;
+      return code < 0x20 || code === 0x7f;
+    }) ||
+    !URL.canParse(value)
+  ) {
+    return false;
+  }
+  return OPENABLE_SCHEMES.has(new URL(value).protocol);
+}
+
+/**
+ * True for an address the page opens for a frame (ADR-0067): a web or a mail address that is not
+ * the console's own, given as `origin`, since a page of the console's is `navigate`'s, in the
+ * person's tab.
+ */
+export function isOpenableFrom(value: unknown, origin: string): value is string {
+  return isBridgeUrl(value) && new URL(value).origin !== origin;
+}
+
 function isTheme(value: unknown): value is Record<string, string> {
   if (!isRecord(value)) {
     return false;
@@ -331,6 +374,8 @@ export function isBridgeToPage(value: unknown): value is BridgeToPage {
       );
     case "download":
       return isLine(value.id, MAX_ID_LENGTH);
+    case "open":
+      return isBridgeUrl(value.url);
     case "subscribe":
       return (
         Array.isArray(value.kinds) &&

package/src/plugin/capabilities.ts

@@ -8,6 +8,8 @@ export const PLUGIN_CAPABILITIES = [
   "files",
   "people:read",
   "people:read:all",
+  "people:read:email",
+  "people:act",
   "projects:read",
   "projects:read:all",
   "board:read",
@@ -60,6 +62,15 @@ export const CAPABILITY_WORDS: Readonly<Record<PluginCapability, CapabilityWords
     opens: "everyone in the workspace, for its jobs and hooks too",
     reach: "the directory",
   },
+  "people:read:email": {
+    opens: "the work email of the people it may read, to match them to accounts elsewhere",
+    reach: "the addresses of the people its role holders may see",
+  },
+  "people:act": {
+    opens:
+      "acting for a person who did something elsewhere: a command run and a decision answered as them, within what they may do, recorded as theirs through the plugin",
+    reach: "what its role holders may do, done in their name from elsewhere",
+  },
   "projects:read": {
     opens: "the projects and members the caller may see",
     reach: "what the person sees",

package/src/plugin/context.ts

@@ -15,6 +15,7 @@ import type {
   RestTask,
   RestTaskInput,
   RestTaskPatch,
+  RestTeam,
 } from "../schemas.js";
 import type { WeekStart } from "../vocabulary.js";
 import type { PluginFileHandle } from "./args.js";
@@ -41,6 +42,16 @@ export type RecordSchemaResult<T> =
 /** The data a record of a collection holds, from its schema. */
 export type RecordData<S> = S extends RecordSchema<infer T> ? T : never;
 
+/**
+ * How long a collection keeps a record: `days` after the moment `by` names, `createdAt` or
+ * `updatedAt` of the record, or an indexed field of its data that holds a day or an instant as
+ * ISO 8601 text; then the console removes the record, with its versions, links and files.
+ */
+export interface CollectionRetention {
+  readonly days: number;
+  readonly by: string;
+}
+
 /** A collection as `defineCollection` yields it: the name, the schema, and what the console indexes and who reads. */
 export interface CollectionDefinition<S extends RecordSchema = RecordSchema> {
   readonly name: string;
@@ -52,6 +63,8 @@ export interface CollectionDefinition<S extends RecordSchema = RecordSchema> {
   readonly read: readonly string[];
   readonly readOwn: readonly string[];
   readonly history: boolean;
+  /** How long a record is kept, or `null` for as long as the plugin is. */
+  readonly retention: CollectionRetention | null;
 }
 
 export interface PluginRecord<T = Record<string, unknown>> {
@@ -209,6 +222,14 @@ export interface PluginInfo {
   readonly board: { readonly id: string; readonly key: string } | null;
   /** The projects the plugin is on: all, or their keys. */
   readonly projects: "all" | readonly string[];
+  /** The roles other plugins granted to this one (ADR-0072), by their key, so that a plugin says what it lacks. */
+  readonly grants: readonly PluginGrantHeld[];
+}
+
+/** A role of another plugin, held by this one. */
+export interface PluginGrantHeld {
+  readonly plugin: string;
+  readonly role: string;
 }
 
 export interface CallerPerson {
@@ -245,14 +266,43 @@ export interface ConsoleCaller {
   readonly project: CallerProject | null;
 }
 
-export type PluginCaller = PersonCaller | ConsoleCaller;
+/**
+ * Another plugin, calling with the roles granted to it (ADR-0072): from its own job, hook or
+ * webhook, as itself; or for a person who did something elsewhere, with `for`, and then with the
+ * roles the plugin and the person both hold, in the person's language. A plugin that knows only
+ * `person` and `console` refuses the kind, which fails safe.
+ */
+export interface PluginAsCaller {
+  readonly kind: "plugin";
+  /** The calling plugin's key. */
+  readonly plugin: string;
+  readonly roles: readonly string[];
+  /** The person the plugin acts for, or `null` when it acts as itself; never an administrator by that. */
+  readonly for: CallerPerson | null;
+  /** The project the call is on, if any: the one the person's own call was on. */
+  readonly project: CallerProject | null;
+}
+
+export type PluginCaller = PersonCaller | ConsoleCaller | PluginAsCaller;
 
 export interface PluginWorkspace {
   readonly name: string;
   readonly languages: readonly string[];
+  /** The zone the workspace's times of day are read in; `UTC` where none is set, as `timeZoneSet` says. */
   readonly timeZone: string;
+  /**
+   * Whether an administrator set the time zone: `false` where the workspace runs on UTC because
+   * nobody said otherwise, so that a plugin that reads a time of day says so, instead of taking
+   * UTC for a choice.
+   */
+  readonly timeZoneSet: boolean;
   /** The day the week begins on (ADR-0035): `auto` leaves it to the language of whoever reads. */
   readonly weekStart: WeekStart;
+  /**
+   * The console's public origin (`PUBLIC_URL`), for a link to the console in what a plugin
+   * writes elsewhere; `null` where the deployment names none.
+   */
+  readonly url: string | null;
   readonly categories: readonly {
     readonly key: string;
     readonly name: string;
@@ -260,6 +310,13 @@ export interface PluginWorkspace {
   }[];
 }
 
+/** An answer given for a person (ADR-0072): the option by its key or by its label, one of the two, and a note. */
+export interface DecisionAnswer {
+  readonly optionKey?: string;
+  readonly option?: string;
+  readonly note?: string;
+}
+
 export interface DecisionAsk {
   /** In the language of whoever is to answer, as `people.get` says it (ADR-0065). */
   readonly question: string;
@@ -287,11 +344,18 @@ export interface PluginConsole {
     get(id: string): Promise<RestPerson | null>;
     /**
      * The active people a role of the plugin was granted to, by name, through a project or with
-     * everyone, and everyone for `defaultRole` (ADR-0063). An administrator holds every role, and
-     * is listed only where they were granted it.
+     * everyone, and everyone for `defaultRole` (ADR-0063); for a role that follows the reporting
+     * line, whoever manages someone besides (ADR-0068). An administrator holds every role, and is
+     * listed only where they were granted it or manage someone.
      */
     granted(role: string): Promise<readonly RestPerson[]>;
   };
+  /** The teams of the workspace (ADR-0073): a name and its members, among the people the caller may see. */
+  teams: {
+    list(): Promise<readonly RestTeam[]>;
+    /** One team by its key (ADR-0074), what a grant and a person's `teams` name it by. */
+    get(key: string): Promise<RestTeam | null>;
+  };
   projects: {
     list(): Promise<readonly RestProject[]>;
     get(key: string): Promise<RestProject | null>;
@@ -308,6 +372,14 @@ export interface PluginConsole {
     list(project: string): Promise<readonly RestDecision[]>;
     get(id: string): Promise<RestDecision | null>;
     ask(project: string, decision: DecisionAsk): Promise<RestDecision>;
+    /**
+     * Answers a decision for a person who answered elsewhere (ADR-0072), with `people:act`: one on
+     * the person's own plate, addressed to them or a plugin's addressed to someone they manage, up
+     * the reporting line (ADR-0068), and `plugin.forbidden` for any other, whatever they
+     * administer or are a member of. The answer is theirs, through this plugin. A plugin answers
+     * no decision itself.
+     */
+    answer(id: string, answer: DecisionAnswer, as: { readonly for: string }): Promise<RestDecision>;
   };
   documents: {
     list(project: string, folder?: string): Promise<readonly RestDocumentSummary[]>;
@@ -342,28 +414,90 @@ export interface PluginSql extends PluginSqlClient {
   transaction<T>(work: (tx: PluginSqlClient) => Promise<T>): Promise<T>;
 }
 
-/** Where the console puts a secret into an outbound request. */
-export type SecretPlacement = `header:${string}` | `query:${string}` | "basic";
+/**
+ * Where the console puts a secret into an outbound request: a header, as `Authorization: Bearer`,
+ * a query parameter, as basic authentication (`user:password`), or a field of a JSON or a form
+ * body.
+ */
+export type SecretPlacement =
+  | `header:${string}`
+  | "bearer"
+  | `query:${string}`
+  | "basic"
+  | `body:${string}`;
+
+/** One secret setting and where it goes. */
+export interface SecretUse {
+  readonly name: string;
+  readonly as: SecretPlacement;
+}
+
+/**
+ * A value of the answer to seal as a secret setting (ADR-0070): the path to it in the answer's
+ * JSON (`$.access_token`, `$.credentials.signing_secret`, `$.items.0.token`), and, where it
+ * expires, how long it lasts, in seconds or as a path to the seconds (`$.expires_in`). The
+ * console seals the value and hands the plugin the answer with `"[sealed]"` in its place.
+ */
+export type SecretSeal =
+  | string
+  | { readonly path: string; readonly expiresIn?: number | string | undefined };
+
+/**
+ * What became of a value `seal` named (ADR-0070). `sealed`: sealed as the setting, the answer
+ * saying `"[sealed]"` in its place. `absent`: nothing at the path (no such key, `null` or an
+ * empty string); nothing sealed, nothing taken out. `not_a_string`, `too_long` and `echoed`: a
+ * value that is no string, is over the bound of a secret (4,096 characters), or holds a secret
+ * the request carried from another setting; never sealed and never handed over, the answer saying
+ * `"[withheld]"` in its place. `not_json`: an answer that is no JSON object or array, whose body
+ * is withheld whole. Only `sealed` changed the setting.
+ */
+export type SealOutcome = "sealed" | "absent" | "not_a_string" | "too_long" | "echoed" | "not_json";
 
 export interface PluginFetchInit {
+  /** `GET` unless said; `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`, and no other. */
   readonly method?: string;
   readonly headers?: Readonly<Record<string, string>>;
   readonly body?: string | Uint8Array;
-  /** A secret setting, put where `as` says: a header, a query parameter, or as basic authentication (`user:password`). */
-  readonly secret?: { readonly name: string; readonly as: SecretPlacement };
-}
-
-/** An outbound answer, whole: the host reads it to the bound before handing it over. */
+  /** A secret setting, put where `as` says. */
+  readonly secret?: SecretUse;
+  /** Several, where a request carries more than one: a client secret in the body and a token as a bearer, say. */
+  readonly secrets?: readonly SecretUse[];
+  /** Values of the answer to seal as secret settings, by the setting's name, never handed to the plugin. */
+  readonly seal?: Readonly<Record<string, SecretSeal>>;
+}
+
+/**
+ * An outbound answer, whole: the host reads it to the bound before handing it over, a redirect as
+ * it is, never followed. Every form of a secret the request carried, and of a value sealed or
+ * withheld, is taken out of its headers and its body first, `"[withheld]"` in its place.
+ */
 export interface PluginFetchResponse {
   readonly status: number;
   readonly headers: Readonly<Record<string, string>>;
   readonly bytes: Uint8Array;
+  /** What became of each value `seal` named, by the setting's name; there where the request named `seal`. */
+  readonly sealed?: Readonly<Record<string, SealOutcome>>;
   text(): string;
   json(): unknown;
 }
 
+/** How a secret stands: whether it is set and not expired, when it expires, and where it came from. */
+export interface SecretStatus {
+  /** Set, and not past its expiry. */
+  readonly set: boolean;
+  readonly setAt: string | null;
+  /** When it expires, or `null` for a secret that does not. */
+  readonly expiresAt: string | null;
+  /** `administrator` for one an administrator set; the host of the answer it was sealed from otherwise; `null` while unset. */
+  readonly source: string | null;
+}
+
 export interface PluginSecrets {
+  /** Whether the secret is set and not past its expiry. */
   has(name: string): Promise<boolean>;
+  /** How the secret stands, for a settings page to say and a job to decide whether to renew it. */
+  status(name: string): Promise<SecretStatus>;
+  /** Signs with the secret; refused for a secret declared `use: "verify"`, which signs nothing. */
   sign(name: string, payload: string | Uint8Array, algorithm: "hmac-sha256"): Promise<string>;
   verify(
     name: string,
@@ -376,6 +510,23 @@ export interface PluginSecrets {
 export interface OtherPlugin {
   readonly version: string;
   readonly api: Readonly<Record<string, (input: unknown) => Promise<unknown>>>;
+  /**
+   * The same plugin, called for a person who did something elsewhere (ADR-0072): with the roles
+   * this plugin and the person both hold in it, in the person's language, what it reads of the
+   * console the person's as a member's, whatever they administer, recorded as theirs through this
+   * plugin. Needs `people:act`; the person is active, or the call is `plugin.not_found`.
+   */
+  for(personId: string): OtherPlugin;
+}
+
+/** The plugin's own endpoints, as a service elsewhere is told to call them. */
+export interface PluginEndpoints {
+  /**
+   * The full address of an endpoint the plugin defines, under the console's public origin, to
+   * register a callback or a webhook with a service elsewhere; `plugin.not_found` for a name the
+   * plugin does not define, `plugin.unavailable` where the console has no public address.
+   */
+  url(name: string): Promise<string>;
 }
 
 export interface PluginLog {
@@ -399,6 +550,7 @@ export interface PluginContext {
   fetch(url: string, init?: PluginFetchInit): Promise<PluginFetchResponse>;
   readonly secrets: PluginSecrets;
   readonly plugins: { get(key: string): Promise<OtherPlugin> };
+  readonly endpoints: PluginEndpoints;
   readonly log: PluginLog;
   now(): Date;
   /** The caller's language, `en` for the console. */
@@ -410,6 +562,14 @@ export interface PluginContext {
 /** An event a hook receives: the console's, of the plugin's board projects, or another plugin's. */
 export interface PluginHookEvent {
   readonly source: "console" | "plugin";
+  /**
+   * The event's id, one per event across both streams (`console:<number>` or `plugin:<number>`):
+   * delivery is at least once, so a hook that must not act twice keeps the ids it acted on and
+   * passes over one it has seen.
+   */
+  readonly id: string;
+  /** Which delivery of the event this is: 1 the first time, more after a failure and its retries. */
+  readonly attempt: number;
   /** `console:<kind>` or `plugin:<key>:<kind>`, as the hook was named. */
   readonly kind: string;
   readonly at: string;

package/src/plugin/define.ts

@@ -6,6 +6,7 @@
 import type { ArgDefinitions, ArgDescription, ArgsOf } from "./args.js";
 import type {
   CollectionDefinition,
+  CollectionRetention,
   EndpointRequest,
   EndpointResponse,
   PluginContext,
@@ -19,6 +20,7 @@ import {
   MAX_PLUGIN_ENDPOINTS,
   MAX_PLUGIN_INDEXES,
   MAX_PLUGIN_OPERATIONS,
+  MAX_PLUGIN_RETENTION_DAYS,
   MIN_PLUGIN_JOB_INTERVAL_MS,
 } from "./limits.js";
 import {
@@ -103,6 +105,13 @@ export interface CollectionInput<S extends RecordSchema> {
   readonly readOwn?: readonly string[];
   /** A version kept per write; on unless said otherwise. */
   readonly history?: boolean;
+  /**
+   * How long a record is kept: `days` (1 to `MAX_PLUGIN_RETENTION_DAYS`) after the moment `by`
+   * names, `createdAt` unless said, `updatedAt`, or an indexed field holding a day or an instant
+   * as ISO 8601 text. The console removes what is past it, with its versions, links and files;
+   * with `history: false`, a light collection for logs and deliveries. Kept for ever when left out.
+   */
+  readonly retention?: { readonly days: number; readonly by?: string };
 }
 
 /** A collection of records the console keeps for the plugin, by name. */
@@ -154,6 +163,24 @@ export function defineCollection<S extends RecordSchema>(
   if (input.readOwn !== undefined && input.owner === undefined) {
     problems.push(`the collection ${name} has readOwn roles and no owner field`);
   }
+  const retention = input.retention;
+  if (retention !== undefined) {
+    if (
+      !Number.isInteger(retention.days) ||
+      retention.days < 1 ||
+      retention.days > MAX_PLUGIN_RETENTION_DAYS
+    ) {
+      problems.push(
+        `the collection ${name} keeps records for ${String(retention.days)} days; 1 to ${MAX_PLUGIN_RETENTION_DAYS}`,
+      );
+    }
+    const by = retention.by ?? "createdAt";
+    if (by !== "createdAt" && by !== "updatedAt" && !indexes.includes(by)) {
+      problems.push(
+        `the collection ${name} keeps records by ${by}, which is neither createdAt, updatedAt nor an indexed field`,
+      );
+    }
+  }
   fail(problems);
   return Object.freeze({
     name,
@@ -165,6 +192,10 @@ export function defineCollection<S extends RecordSchema>(
     read: Object.freeze([...(input.read ?? [])]),
     readOwn: Object.freeze([...(input.readOwn ?? [])]),
     history: input.history ?? true,
+    retention:
+      input.retention === undefined
+        ? null
+        : Object.freeze({ days: input.retention.days, by: input.retention.by ?? "createdAt" }),
   });
 }
 
@@ -595,6 +626,8 @@ export interface CollectionDescription {
   readonly read: readonly string[];
   readonly readOwn: readonly string[];
   readonly history: boolean;
+  /** How long a record is kept, or `null` for as long as the plugin is; none from a plugin built before it. */
+  readonly retention?: CollectionRetention | null | undefined;
 }
 
 export interface EndpointDescription {
@@ -670,6 +703,7 @@ export function describePlugin(definition: PluginDefinition): PluginDescription
       read: [...collection.read],
       readOwn: [...collection.readOwn],
       history: collection.history,
+      retention: collection.retention ?? null,
     })),
     commands: Object.fromEntries(
       Object.entries(definition.commands).map(([name, command]) => [

package/src/plugin/limits.ts

@@ -10,6 +10,8 @@ export const MAX_PLUGIN_AGENT_NOTE_LENGTH = 200;
 export const MAX_PLUGIN_KEY_LENGTH = 32;
 /** How many roles, settings, groups of settings, pages and widgets one manifest declares. */
 export const MAX_PLUGIN_ROLES = 10;
+/** How many other plugins one plugin may ask roles of (ADR-0072). */
+export const MAX_PLUGIN_GRANTS_ASKED = 10;
 export const MAX_PLUGIN_SETTINGS = 50;
 export const MAX_PLUGIN_SETTING_GROUPS = 10;
 export const MAX_PLUGIN_PAGES = 12;
@@ -42,6 +44,8 @@ export const MAX_PLUGIN_COMMAND_FILES = 20;
 export const MAX_PLUGIN_EVENT_BYTES = 16 * 1024;
 export const PLUGIN_EVENTS_KEPT = 100_000;
 export const PLUGIN_EVENT_DAYS = 90;
+/** The most days a collection's retention may keep a record: ten years. */
+export const MAX_PLUGIN_RETENTION_DAYS = 3650;
 /** How many records one page of a list carries at most. */
 export const PLUGIN_LIST_LIMIT = 200;
 /** How long plugin code may run: a command; a query or an endpoint; a hook; a job; `onEnable`, `onDisable` and an upgrade. */

package/src/plugin/manifest.ts

@@ -14,6 +14,7 @@ import {
   MAX_PLUGIN_AGENT_NOTE_LENGTH,
   MAX_PLUGIN_CAPABILITIES,
   MAX_PLUGIN_DESCRIPTION_LENGTH,
+  MAX_PLUGIN_GRANTS_ASKED,
   MAX_PLUGIN_NAME_LENGTH,
   MAX_PLUGIN_OPTIONS,
   MAX_PLUGIN_PAGES,
@@ -212,7 +213,28 @@ export const PLUGIN_BOARD_NEEDS = ["required", "optional", "none"] as const;
 export type PluginBoardNeeds = (typeof PLUGIN_BOARD_NEEDS)[number];
 
 const LANGUAGE_TAG = /^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
-const DAY = /^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$/;
+const DAY = /^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/;
+
+/**
+ * True for a day as `YYYY-MM-DD` that the calendar has: February 30 and April 31 fit the shape
+ * and are no day, and a date made from them comes back as another day.
+ */
+export function isCalendarDay(value: unknown): value is string {
+  if (typeof value !== "string") {
+    return false;
+  }
+  const match = DAY.exec(value);
+  if (match === null) {
+    return false;
+  }
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return (
+    date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day
+  );
+}
 /** A time of day as `HH:MM`, read in the workspace's time zone. */
 export const TIME_OF_DAY = /^(?:[01]\d|2[0-3]):[0-5]\d$/;
 /** A path within the package: relative, forward slashes, never climbing out. */
@@ -290,6 +312,10 @@ const pluginSettingSchema = z
     of: z.optional(settingItemType),
     /** The group of `settingGroups` the setting is shown under; left out, above every group. */
     group: z.optional(key),
+    /** For a `secret`: the hosts it may be put into a request to and sealed from the answers of (`slack.com`, `*.example.com`), and no other; any host the plugin may reach when left out. */
+    hosts: z.optional(z.array(z.string().check(z.maxLength(300))).check(z.maxLength(20))),
+    /** For a `secret`: `verify`, a secret that verifies signatures and signs nothing, so that a request cannot be forged with it. */
+    use: z.optional(z.literal("verify")),
   })
   .check(
     z.superRefine((setting, ctx) => {
@@ -327,7 +353,7 @@ function fitsSettingType(
     case "enum":
       return typeof value === "string" && (options ?? []).includes(value);
     case "day":
-      return typeof value === "string" && DAY.test(value);
+      return isCalendarDay(value);
     case "time":
       return typeof value === "string" && TIME_OF_DAY.test(value);
     case "person":
@@ -345,8 +371,18 @@ function settingProblems(setting: {
   max?: number;
   options?: readonly { value: string }[];
   of?: Exclude<PluginSettingType, "secret" | "list">;
+  hosts?: readonly string[];
+  use?: "verify";
 }): string[] {
   const problems: string[] = [];
+  if (setting.type !== "secret" && (setting.hosts !== undefined || setting.use !== undefined)) {
+    problems.push(`only a secret takes hosts or use`);
+  }
+  for (const host of setting.hosts ?? []) {
+    if (!isPluginCapability(`outbound:${host}`) || host === "webrtc") {
+      problems.push(`the host "${host}" is not a host as outbound:<host> names one`);
+    }
+  }
   const bounded =
     setting.type === "number" ||
     setting.type === "text" ||
@@ -503,6 +539,11 @@ export type PluginBoard = z.infer<typeof pluginBoardSchema>;
 const pluginRoleSchema = z.strictObject({
   name: localized(MAX_PLUGIN_NAME_LENGTH),
   description: localized(MAX_PLUGIN_DESCRIPTION_LENGTH),
+  /**
+   * A role held by what a person is in the directory, with no grant (ADR-0068): `reports`,
+   * whoever someone active reports to, read from the directory on every call.
+   */
+  follows: z.optional(z.literal("reports")),
 });
 
 export type PluginRole = z.infer<typeof pluginRoleSchema>;
@@ -545,6 +586,20 @@ export const pluginManifestSchema = z
       z.record(key, z.string().check(z.regex(SEMVER_RANGE, "is a semver range"))),
       {},
     ),
+    /**
+     * The roles of other plugins the plugin asks to hold (ADR-0072), by their key, each with why,
+     * for the administrator who grants them: shown when enabling and on the plugin's page.
+     */
+    grants: z._default(
+      z.record(
+        key,
+        z.strictObject({
+          roles: z.array(key).check(z.minLength(1), z.maxLength(MAX_PLUGIN_ROLES)),
+          why: localized(MAX_PLUGIN_DESCRIPTION_LENGTH),
+        }),
+      ),
+      {},
+    ),
     board: z._default(pluginBoardSchema, { needs: "none" }),
     settings: z._default(z.array(pluginSettingSchema).check(z.maxLength(MAX_PLUGIN_SETTINGS)), []),
     settingGroups: z._default(
@@ -559,7 +614,17 @@ export const pluginManifestSchema = z
   })
   .check(
     z.superRefine((manifest, ctx) => {
-      for (const problem of manifestProblems(manifest)) {
+      for (const problem of [
+        ...manifestProblems(manifest),
+        ...(manifest.key in manifest.grants ? ["grants: a plugin asks nothing of itself"] : []),
+        // Its own api through `ctx.plugins` would be itself called as another plugin, and, with
+        // `people:act`, every call of its own made for anyone (ADR-0072).
+        ...(capabilitiesAsked(manifest).includes(`plugins:${manifest.key}`)
+          ? [
+              `capabilities: plugins:${manifest.key} is the plugin itself; a plugin calls no api of its own`,
+            ]
+          : []),
+      ]) {
         ctx.addIssue({ code: "custom", message: problem, input: manifest });
       }
     }),
@@ -588,6 +653,12 @@ function manifestProblems(
   if (roles.length > MAX_PLUGIN_ROLES) {
     problems.push(`declares ${roles.length} roles; ${MAX_PLUGIN_ROLES} at most`);
   }
+  const pluginsAsked = Object.keys(manifest.grants);
+  if (pluginsAsked.length > MAX_PLUGIN_GRANTS_ASKED) {
+    problems.push(
+      `asks roles of ${pluginsAsked.length} plugins; ${MAX_PLUGIN_GRANTS_ASKED} at most`,
+    );
+  }
   if (manifest.defaultRole !== undefined && !roles.includes(manifest.defaultRole)) {
     problems.push(`defaultRole ${manifest.defaultRole} is not a declared role`);
   }