@openbrf/plugin-sdk 0.0.0-stage → 1.0.0

package/src/action-schema.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+
+import type { StandardSchemaV1 } from "./standard-schema.ts";
+
+/**
+ * An action's schemas, as the JSON Schema a caller is published.
+ *
+ * The only call to `z.toJSONSchema` in the product. Every option here is set
+ * against a failure that would otherwise be silent, so they are worth reading
+ * one at a time.
+ *
+ * `io: "input"` because output mode makes a key with a default REQUIRED, and a
+ * model reading that will dutifully supply a value for every field the platform
+ * was perfectly happy to choose itself.
+ *
+ * `cycles: "throw"` because a self-referential schema has no JSON Schema
+ * without `$ref`, and a silently emitted `$ref` to a positional name is worse
+ * than a refusal at registration.
+ *
+ * `reused: "inline"` because `$defs` invents names from the position a schema
+ * happens to hold, and those names would reach a committed artefact and a
+ * third-party client. Inlining costs bytes and keeps the document stable.
+ *
+ * The function form of `unrepresentable` because the default error names
+ * neither the action nor the path, and a build failing with "unrepresentable
+ * type" and nothing else is a half hour of searching.
+ *
+ * One property is worth stating because it is NOT what one would assume: a bare
+ * `.transform()` does not throw under input mode - it is erased and the
+ * pre-transform type is emitted. The guarantee is placed where it is real, on
+ * the output helper, which does throw. So an action whose pair is converted at
+ * registration cannot carry a transform anywhere.
+ *
+ * `.refine()`, `.check()`, `.superRefine()` and `.brand()` are erased with no
+ * marker under both modes. That is why the rule for a published schema is
+ * structural constraints first: what the document says has to be at least as
+ * strict as what the runtime enforces, or a caller is told a value is
+ * acceptable that the service will refuse.
+ */
+
+/** Refuses a schema built with a second copy of zod, whose internals differ. */
+export function isHostZodSchema(schema: unknown): schema is z.ZodType {
+  return (
+    typeof schema === "object" &&
+    schema !== null &&
+    "_zod" in schema &&
+    (schema as { _zod?: unknown })._zod !== undefined
+  );
+}
+
+function convert(
+  schema: unknown,
+  actionName: string,
+  io: "input" | "output",
+): Record<string, unknown> {
+  if (!isHostZodSchema(schema)) {
+    throw new Error(
+      `${actionName}: an action schema must be built with the host's zod.`,
+    );
+  }
+  return z.toJSONSchema(schema, {
+    target: "draft-2020-12",
+    io,
+    cycles: "throw",
+    reused: "inline",
+    unrepresentable: ({ path, message }) => {
+      throw new Error(
+        `${actionName}: ${message} at ${[io, ...path.map(String)].join(".")}`,
+      );
+    },
+  }) as Record<string, unknown>;
+}
+
+export function actionInputJsonSchema(
+  schema: StandardSchemaV1<unknown, unknown>,
+  actionName: string,
+): Record<string, unknown> {
+  return convert(schema, actionName, "input");
+}
+
+export function actionOutputJsonSchema(
+  schema: StandardSchemaV1<unknown, unknown>,
+  actionName: string,
+): Record<string, unknown> {
+  return convert(schema, actionName, "output");
+}

package/src/actions.ts

@@ -0,0 +1,247 @@
+import type { StandardSchemaV1 } from "./standard-schema.ts";
+
+/**
+ * What the platform can be asked to do, declared once and dispatched through
+ * one place: an action (atgard).
+ *
+ * An action is a name, an input schema, the single capability it needs, what it
+ * does to the records, which categories of personal data it can touch, and which
+ * surfaces it may be offered on. The registry checks the calling person's
+ * capability on every call rather than trusting the caller, so registering an
+ * action is never a permission of its own - it is a way of reaching something
+ * the caller could already do.
+ *
+ * A core feature registers its own. A plugin registers the ones its manifest
+ * declared and the board consented to, and they disappear with the plugin.
+ *
+ * Swedish domain terms follow GLOSSARY.md.
+ */
+
+export const ACTION_EFFECTS = ["read", "write", "delete"] as const;
+export type ActionEffect = (typeof ACTION_EFFECTS)[number];
+
+/**
+ * Where an action may be offered.
+ *
+ * "ui" means in-process only: the platform's own screens and a plugin's own
+ * route. The other two are the ones a board switches on deliberately.
+ */
+export const ACTION_SURFACES = ["ui", "mcp", "ai"] as const;
+export type ActionSurface = (typeof ACTION_SURFACES)[number];
+
+/**
+ * What an action can touch.
+ *
+ * The first thirteen are PERSONAL_DATA_CATEGORIES from @openbrf/shared, in
+ * order, which this package deliberately does not depend on; the API side
+ * asserts the prefix equality, because it is the only place that can import
+ * both. "protected" is this list's own and marks an action that can return a
+ * field of a person carrying protected personal data (skyddade
+ * personuppgifter): it is the value the registry refuses to expose to a
+ * connected app or to the AI package at all.
+ */
+export const ACTION_PERSONAL_DATA = [
+  "name",
+  "apartment",
+  "residency",
+  "email",
+  "phone",
+  "postalAddress",
+  "personalIdentityNumber",
+  "account",
+  "financial",
+  "health",
+  "photograph",
+  "freeText",
+  "auditTrail",
+  "protected",
+] as const;
+export type ActionPersonalData = (typeof ACTION_PERSONAL_DATA)[number];
+
+/**
+ * What a public action name may look like.
+ *
+ * The intersection of three separate limits: what an MCP tools/list entry
+ * allows, what a model API allows (no dots), and what stays readable in a
+ * directory review (64 characters).
+ */
+export const ACTION_NAME_PATTERN = /^[a-z][a-z0-9_]{2,63}$/;
+
+/** What a refusal means for a caller that is a model rather than a person. */
+export interface ActionErrorSpec {
+  /** The machine-readable reason the handler raises. */
+  readonly reason: string;
+  /** Whether trying again could ever work, and after what. */
+  readonly retry: "never" | "after-edit" | "after-backoff";
+  /** The sentence a person is shown, as an i18n key. */
+  readonly messageKey: string;
+}
+
+/**
+ * The request a plugin's own route received.
+ *
+ * Opaque on purpose: the host reads a symbol on it that only the host writes,
+ * so a plugin passes the request it was handed straight through and cannot
+ * construct one. That is what stops a plugin naming a person it was not given.
+ */
+export type ActionRequest = object;
+
+/** The lowercase channel vocabulary. The registry maps it to the audit channel. */
+export const ACTION_CHANNELS = [
+  "web",
+  "mcp",
+  "ai",
+  "system",
+  "plugin",
+] as const;
+export type ActionChannel = (typeof ACTION_CHANNELS)[number];
+
+/**
+ * Who is acting.
+ *
+ * The person, and the capabilities the registry re-derived for this call. No
+ * email, no name, no roles: a handler that needs to decide what an audience may
+ * see reads the capability list, and a handler that does not need it is not
+ * given a person's details to leak.
+ */
+export interface ActionPrincipal {
+  readonly personId: string;
+  readonly capabilities: readonly string[];
+}
+
+/** The connected app that acted, when one did. Both hosts, never the token. */
+export interface ActionClient {
+  readonly clientId: string;
+  readonly clientHost: string | null;
+}
+
+/** What a handler is told about the call. Built by the host, never by a caller. */
+export interface ActionContext {
+  readonly principal: ActionPrincipal;
+  readonly channel: ActionChannel;
+  readonly client?: ActionClient;
+  readonly requestId: string;
+  readonly now: Date;
+}
+
+export interface ActionDefinition<Input = unknown, Output = unknown> {
+  readonly name: string;
+  readonly titleKey: string;
+  readonly descriptionKey: string;
+  readonly group: string;
+  readonly groupTitleKey: string;
+  /** Exactly one core capability, by name. */
+  readonly capability: string;
+  readonly effect: ActionEffect;
+  readonly idempotent: boolean;
+  /**
+   * True when the act adds and overwrites nothing a person wrote.
+   *
+   * It is what separates a create from an update, and the annotation mapping
+   * reads it: MCP's destructiveHint defaults to true, so a non-read action has
+   * to say for itself that it destroys nothing.
+   */
+  readonly additive: boolean;
+  readonly needsConfirmation: boolean;
+  /** True when the handler reaches a system outside this instance. */
+  readonly openWorld: boolean;
+  /** Never empty by convention: an action that touches none says []. */
+  readonly personalData: readonly ActionPersonalData[];
+  /** Opt-in allowlist. An empty array means the action is offered nowhere. */
+  readonly surfaces: readonly ActionSurface[];
+  /** Every domain refusal the handler can raise, for the caller to act on. */
+  readonly errors: readonly ActionErrorSpec[];
+  readonly deprecatedAliases?: readonly string[];
+  /** Every object in it, at every depth, must refuse unknown keys. */
+  readonly input: StandardSchemaV1<unknown, Input>;
+  readonly output: StandardSchemaV1<unknown, Output>;
+  readonly handler: (input: Input, context: ActionContext) => Promise<Output>;
+}
+
+/**
+ * What a plugin hands the host: the id its manifest declared, and the rest.
+ *
+ * The capability, the effect, the personal-data categories and the surfaces are
+ * manifest data and are not repeated here. The loader's rule is that nothing
+ * which can refuse a plugin may run after the code that executes it, and the
+ * install consent screen renders from the catalog before anything is
+ * downloaded - so what the board consents to cannot come from the bundle.
+ */
+export interface PluginActionRegistration {
+  readonly id: string;
+  readonly definition: Omit<
+    ActionDefinition,
+    "capability" | "effect" | "personalData" | "surfaces"
+  >;
+}
+
+/** Narrows what a plugin's route offers the request it is serving. */
+export interface PluginActionFilter {
+  readonly surface?: ActionSurface;
+  readonly group?: string;
+}
+
+/** One action as a caller sees it, with its text already in the right language. */
+export interface ActionSummary {
+  readonly name: string;
+  readonly title: string;
+  readonly description: string;
+  readonly titleKey: string;
+  readonly descriptionKey: string;
+  readonly group: string;
+  readonly groupTitle: string;
+  /**
+   * The key behind `groupTitle`, alongside the two above.
+   *
+   * Both forms travel for the reason `titleKey` does: the resolved string is
+   * for a caller with no translations of its own - a connected app, a model -
+   * while a screen in this product translates the key itself. The interface's
+   * language and the language a request happens to declare are not the same
+   * thing, so a screen rendering the resolved string can show one heading in
+   * the browser's language above a page in the association's.
+   */
+  readonly groupTitleKey: string;
+  readonly capability: string;
+  readonly effect: ActionEffect;
+  readonly idempotent: boolean;
+  readonly additive: boolean;
+  readonly needsConfirmation: boolean;
+  readonly openWorld: boolean;
+  readonly personalData: readonly ActionPersonalData[];
+  readonly surfaces: readonly ActionSurface[];
+  readonly errors: readonly ActionErrorSpec[];
+}
+
+export interface PluginActions {
+  /**
+   * Registers an action the manifest declared.
+   *
+   * Callable from the module factory onwards: a call made that early is
+   * buffered until the application is built, because the host object is not
+   * bound yet.
+   *
+   * It does not throw for a registration the host will refuse. An id the
+   * manifest never declared, or a schema that cannot be published, is found
+   * when the buffer is flushed - long after this call returned - and reaches
+   * the board as an `action-refused` finding rather than as an error the
+   * factory could have caught. A plugin that wants to know sooner validates
+   * its own manifest in its own build.
+   */
+  register: (registration: PluginActionRegistration) => void;
+
+  /** What this plugin's route may offer the request it is serving. */
+  list: (
+    request: ActionRequest,
+    filter?: PluginActionFilter,
+  ) => Promise<ActionSummary[]>;
+
+  /**
+   * Dispatch. The person, the channel and the connected app all come from the
+   * request the host authenticated, never from an argument.
+   */
+  invoke: <Output>(
+    request: ActionRequest,
+    name: string,
+    input: unknown,
+  ) => Promise<Output>;
+}

package/src/api-version.ts

@@ -0,0 +1,28 @@
+/**
+ * The plugin API version.
+ *
+ * A single integer rather than a semver range, because the gate it guards is
+ * binary: a plugin either speaks the contract this host implements or it does
+ * not get loaded. A range would invite a plugin to claim ">=1" and then fail
+ * at the first call to a method version 2 removed, which is exactly the class
+ * of breakage the gate exists to prevent.
+ *
+ * Additive changes - a new optional manifest field, a new SDK method - keep
+ * the number. Anything a plugin built against the old contract could notice
+ * raises it, and the host may then support more than one version at a time by
+ * listing them in SUPPORTED_PLUGIN_API_VERSIONS.
+ */
+export const PLUGIN_API_VERSION = 1;
+
+/**
+ * Every version this contract can still load. Kept as a list so a host can
+ * carry an old version through a deprecation window without a plugin having
+ * to be republished on the day the new one lands.
+ */
+export const SUPPORTED_PLUGIN_API_VERSIONS: readonly number[] = [
+  PLUGIN_API_VERSION,
+];
+
+export function isSupportedApiVersion(apiVersion: number): boolean {
+  return SUPPORTED_PLUGIN_API_VERSIONS.includes(apiVersion);
+}

package/src/catalog.ts

@@ -0,0 +1,236 @@
+import { z } from "zod";
+
+import { IntegrityError, parseSha512 } from "./integrity.ts";
+import {
+  declaredActionsSchema,
+  pluginActionSchema,
+  pluginIdSchema,
+  pluginManifestSchema,
+} from "./manifest.ts";
+import {
+  PLUGIN_PERMISSIONS,
+  PLUGIN_PERSONAL_DATA_CATEGORIES,
+} from "./permissions.ts";
+
+/**
+ * The catalog index.
+ *
+ * One file listing everything an instance may install: plugins and themes
+ * alike, since both are distributed the same way and the board browses one
+ * screen per kind rather than one source per kind. Delisting is a commit
+ * against the index, which is why an instance re-reads it rather than caching
+ * it across installs.
+ *
+ * Exported so the index is checked by the same schema wherever it is read: by
+ * the instance before it offers an entry to a board, and by the catalog's own
+ * check before a listing is merged.
+ *
+ * Entries are parsed strictly. The index arrives over the network, and an
+ * entry the instance does not fully understand is an entry it must not offer
+ * to a board for consent - the consent screen's whole job is to say precisely
+ * what is being agreed to.
+ *
+ * Every object in it is strict as well: a field this version of the index does
+ * not define is refused, never dropped. Dropped, a misspelled field of the
+ * declaration would be replaced by its default before the consent screen or
+ * 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.
+ */
+
+/** Whether `declared` is a digest `parseSha512` can read. */
+function isReadableSha512(declared: string): boolean {
+  try {
+    parseSha512(declared);
+    return true;
+  } catch (error) {
+    if (error instanceof IntegrityError) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+/** A tarball and the digest its bytes must hash to. */
+export const catalogArtifactSchema = z.strictObject({
+  /**
+   * Direct URL.
+   *
+   * https on a curated instance, and nothing else: the shape is checked here
+   * but the destination is decided at fetch time, where http: and file: are
+   * refused unless the instance has opted out of curation. That is what keeps
+   * an entry - which is data fetched from elsewhere - from naming a `file:`
+   * path and having the instance read its own disk, or a plain-http address
+   * inside the network the instance sits in.
+   */
+  url: z.string().min(1).max(2000),
+  /**
+   * "sha512-<base64>" or 128 hex characters.
+   *
+   * Read through the same `parseSha512` the instance verifies a download with,
+   * so an entry the catalog's check lets through is one the instance can read,
+   * and an index with a badly spelled digest is refused by `parseCatalogIndex`
+   * alone.
+   */
+  sha512: z.string().min(1).max(200).refine(isReadableSha512, {
+    error:
+      'Expected a digest written as "sha512-<base64>" or 128 hex characters.',
+  }),
+  bytes: z.int().min(1).optional(),
+});
+
+export type CatalogArtifact = z.infer<typeof catalogArtifactSchema>;
+
+/** Text a curator writes in both languages the interface is offered in. */
+const localizedTextSchema = z.strictObject({
+  sv: z.string().min(1).max(500),
+  en: z.string().min(1).max(500),
+});
+
+export type LocalizedText = z.infer<typeof localizedTextSchema>;
+
+/** Strict, and `.extend()` keeps it so for both kinds of entry. */
+const baseEntrySchema = z.strictObject({
+  /**
+   * Unique across the whole index, whatever the entry's type: an install
+   * looks an entry up by id alone.
+   */
+  id: pluginIdSchema,
+  version: z.string().min(1).max(64),
+  /** The curator's text, in both languages the interface is offered in. */
+  name: localizedTextSchema,
+  description: localizedTextSchema,
+  artifact: catalogArtifactSchema,
+  homepage: z.string().max(2000).optional(),
+  /** Set on an entry that is still listed but should not be installed anew. */
+  deprecated: z.boolean().default(false),
+});
+
+export const catalogPluginEntrySchema = baseEntrySchema.extend({
+  type: z.literal("plugin"),
+  /**
+   * The npm package name the tarball unpacks as. Needed because the installer
+   * writes a dependency set for npm, which keys on the package name and not on
+   * the catalog id.
+   */
+  packageName: z.string().min(1).max(214),
+  /** Gated against the host's own contract version before an install starts. */
+  apiVersion: z.int().min(1),
+  /**
+   * Repeated from the plugin's manifest so the consent screen can be shown
+   * before anything is downloaded. The installed manifest is authoritative:
+   * the loader compares the two and refuses a plugin that asks for more than
+   * the board consented to.
+   */
+  permissions: z.array(z.enum(PLUGIN_PERMISSIONS)).max(16).default([]),
+  personalData: z
+    .array(z.enum(PLUGIN_PERSONAL_DATA_CATEGORIES))
+    .max(16)
+    .default([]),
+  /**
+   * The actions the plugin proposes, on the same terms as the two above.
+   *
+   * The widest part of the declaration, and so the part the consent screen
+   * most needs before anything is downloaded: an action names a capability and
+   * offers it to callers the board decides on.
+   *
+   * The manifest's own action fields and its own uniqueness rule, not a
+   * second array of the same thing: the rule on the ids has to hold at
+   * whichever boundary is read first, and two copies is two places for it to
+   * stop holding. Read strictly here, as everything in the index is.
+   */
+  actions: declaredActionsSchema(pluginActionSchema.strict()).default([]),
+  /**
+   * The route that serves MCP, repeated on the same terms as the three above.
+   *
+   * Both rules about it are decided before anything is downloaded - a second
+   * plugin declaring it is refused, and the reserved id `mcp-connector` may be
+   * taken only by a plugin that does declare it - so the index has to carry it.
+   * The manifest's own field schema rather than a second spelling of it: the
+   * value becomes a URL an unauthenticated caller is pointed at, and one
+   * definition of what it may contain is the point of that schema.
+   */
+  oauthProtectedResource: pluginManifestSchema.shape.oauthProtectedResource,
+});
+
+/**
+ * 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
+ * the theme installer's business, not this schema's.
+ *
+ * No package name: a theme is data read out of its archive, never an npm
+ * package, and nothing that installs one keys on a package name.
+ */
+export const catalogThemeEntrySchema = baseEntrySchema.extend({
+  type: z.literal("theme"),
+  /** The token contract range the theme was authored against. */
+  contract: z.string().min(1).max(64).optional(),
+  /** The theme it inherits from, as its manifest names it. */
+  extends: z.string().min(1).max(64).optional(),
+});
+
+export const catalogEntrySchema = z.discriminatedUnion("type", [
+  catalogPluginEntrySchema,
+  catalogThemeEntrySchema,
+]);
+
+export type CatalogPluginEntry = z.infer<typeof catalogPluginEntrySchema>;
+export type CatalogThemeEntry = z.infer<typeof catalogThemeEntrySchema>;
+export type CatalogEntry = z.infer<typeof catalogEntrySchema>;
+
+export const catalogSchema = z
+  .strictObject({
+    /** Index format version, so a future shape can be recognised and refused. */
+    version: z.literal(1),
+    entries: z.array(catalogEntrySchema).max(500),
+  })
+  .superRefine((catalog, ctx) => {
+    /*
+     * 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 type Catalog = z.infer<typeof catalogSchema>;
+
+export type CatalogParseResult =
+  { ok: true; value: Catalog } | { ok: false; issues: readonly string[] };
+
+/**
+ * Parses a catalog index.
+ *
+ * A single malformed entry rejects the whole index rather than being dropped
+ * quietly. A board that installs from a catalog which silently lost an entry
+ * has no way to tell that from an entry that was delisted on purpose, and the
+ * two mean opposite things.
+ *
+ * Returns a result rather than throwing, as `parsePluginPackage` does, so a
+ * catalog's own check can list every problem at once.
+ */
+export function parseCatalogIndex(input: unknown): CatalogParseResult {
+  const result = catalogSchema.safeParse(input);
+  if (result.success) {
+    return { ok: true, value: result.data };
+  }
+  return {
+    ok: false,
+    issues: result.error.issues.map(
+      (issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`,
+    ),
+  };
+}

package/src/define-plugin.ts

@@ -0,0 +1,18 @@
+import type { PluginModuleFactory } from "./module.ts";
+
+/**
+ * Declares a plugin's server entry point.
+ *
+ * Deliberately an identity function. ADR 0003 requires a plugin to ship a
+ * prebuilt CJS bundle whose only externals are host packages, so anything
+ * this helper did at runtime would either have to be bundled into every
+ * plugin or would make the SDK a runtime dependency the host has to resolve
+ * for it. Being identity means a bundler inlines it to nothing and the value
+ * the helper adds - the type of the factory, checked at the author's build
+ * time - costs the running instance nothing.
+ */
+export function definePlugin(
+  factory: PluginModuleFactory,
+): PluginModuleFactory {
+  return factory;
+}

package/src/findings.ts

@@ -0,0 +1,71 @@
+/**
+ * Why a plugin on the data volume is not running.
+ *
+ * A finding travels as one of these codes plus the values its sentence needs,
+ * never as a sentence composed by the host. The interface is Swedish by
+ * default and this package is English, so what a board reads has to be a
+ * translation of the code: a sentence written where the finding is produced
+ * reaches the board panel in the language the server happens to be written in.
+ *
+ * Listed as values rather than as a bare union so a caller can walk them and
+ * prove it has a sentence for each. Part of the contract rather than an
+ * implementation detail - docs/plugin-contract.md lists the same set, and a
+ * plugin author reading why their package was skipped is reading one of these.
+ */
+export const PLUGIN_FINDING_REASONS = [
+  /** The `openbrf` field failed validation. */
+  "manifest-invalid",
+  /** Built against a contract version this instance does not implement. */
+  "api-version-unsupported",
+  /** A declared entry file is not in the package. */
+  "entry-missing",
+  /** The server bundle does not export `createPlugin`. */
+  "entry-invalid",
+  /** `createPlugin` returned no NestJS dynamic module. */
+  "module-invalid",
+  /** Its module declares behaviour a plugin may not register. */
+  "module-refused",
+  /** Its module could not be built into the application. */
+  "module-failed",
+  /** The package carries its own copy of a host package it must share. */
+  "module-identity",
+  /** It asks for more than was consented to. */
+  "permissions-widened",
+  /** It handles a personal-data category that was not consented to. */
+  "personal-data-widened",
+  /** On the volume with no record of consent. */
+  "not-consented",
+  /** Switched off in the admin interface. */
+  "disabled",
+  /** It threw while being loaded. */
+  "load-failed",
+  /** Recorded as installed but not present. */
+  "not-on-volume",
+  /** The installed version declares an action the board did not consent to. */
+  "actions-widened",
+  /** An action the manifest declares could not be registered. */
+  "action-refused",
+  /** One of its providers reaches for a core service a plugin may not hold. */
+  "forbidden-injection",
+  /**
+   * It declares the OAuth protected resource, and another installed plugin
+   * already does. The one installed first keeps it: the resource URL is the
+   * audience every issued token carries, so moving it would strand them all.
+   */
+  "oauth-resource-conflict",
+] as const;
+
+export type PluginFindingReason = (typeof PLUGIN_FINDING_REASONS)[number];
+
+/**
+ * The values a finding's sentence is completed with.
+ *
+ * Identifiers, paths, numbers and what a thrown error said - never a sentence,
+ * and never personal data. A list stays a list rather than being joined here,
+ * because its members can have sentences of their own: a board told that a
+ * package handles a category it never agreed to has to read that category in
+ * its own language, not as `residency`.
+ */
+export type PluginFindingDetail = Readonly<
+  Record<string, string | number | readonly string[]>
+>;