@openbrf/plugin-sdk 0.0.0-stage → 1.0.0

package/dist/findings.js

@@ -0,0 +1,57 @@
+/**
+ * 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",
+];
+//# sourceMappingURL=findings.js.map

package/dist/findings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings.js","sourceRoot":"","sources":["../src/findings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,6CAA6C;IAC7C,kBAAkB;IAClB,yEAAyE;IACzE,yBAAyB;IACzB,mDAAmD;IACnD,eAAe;IACf,wDAAwD;IACxD,eAAe;IACf,wDAAwD;IACxD,gBAAgB;IAChB,+DAA+D;IAC/D,gBAAgB;IAChB,0DAA0D;IAC1D,eAAe;IACf,wEAAwE;IACxE,iBAAiB;IACjB,8CAA8C;IAC9C,qBAAqB;IACrB,qEAAqE;IACrE,uBAAuB;IACvB,+CAA+C;IAC/C,eAAe;IACf,2CAA2C;IAC3C,UAAU;IACV,mCAAmC;IACnC,aAAa;IACb,6CAA6C;IAC7C,eAAe;IACf,6EAA6E;IAC7E,iBAAiB;IACjB,+DAA+D;IAC/D,gBAAgB;IAChB,6EAA6E;IAC7E,qBAAqB;IACrB;;;;OAIG;IACH,yBAAyB;CACjB,CAAC"}

package/dist/host.d.ts

@@ -0,0 +1,208 @@
+import type { PluginActions } from "./actions.ts";
+import type { PluginPermission } from "./permissions.ts";
+import type { PluginSettingsValues } from "./settings-schema.ts";
+/**
+ * The host services a plugin receives.
+ *
+ * Every service is present on the object whether or not the plugin declared
+ * the permission it needs; the ones it did not declare throw
+ * PluginPermissionError on use. Handing out nulls instead would push a
+ * null-check into every call site of a plugin that did declare the permission,
+ * for the sake of a case the plugin author has already ruled out by writing
+ * the manifest. `permissions` is on the object for the plugin that genuinely
+ * wants to degrade rather than fail.
+ */
+export declare class PluginPermissionError extends Error {
+    readonly pluginId: string;
+    readonly permission: PluginPermission;
+    constructor(pluginId: string, permission: PluginPermission);
+}
+/**
+ * Writes to the host's log, tagged with the plugin's id.
+ *
+ * A plugin must not reach for console: its output would be indistinguishable
+ * from the core's, and an operator reading a log needs to know which plugin
+ * produced a line before they can decide whether to disable it.
+ */
+export interface PluginLogger {
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string, cause?: unknown): void;
+}
+/** The plugin's own settings, validated against its declared settingsSchema. */
+export interface PluginSettings {
+    /**
+     * The stored values, with declared defaults applied. Reads the current
+     * values on each call rather than caching, so a change made in the admin
+     * interface reaches a long-running job without a restart.
+     */
+    read(): Promise<PluginSettingsValues>;
+}
+export interface PluginMailMessage {
+    to: string;
+    subject: string;
+    /**
+     * The body, as text.
+     *
+     * Blank lines separate paragraphs; the host renders them in the house style
+     * and escapes them. There is no markup parameter, and that is the point: a
+     * message sent here leaves under the cooperative's own address and passes
+     * its DKIM signature, so a link, an image or a styled block a plugin put in
+     * it would be a link, an image or a styled block the cooperative appears to
+     * have written. A plugin that interpolates a resident's own text into a
+     * body - the ordinary case, and the one that actually happens - cannot turn
+     * it into markup from here.
+     */
+    text: string;
+}
+/**
+ * Sends mail through the instance's configured SMTP server.
+ *
+ * The from address is the instance's and is not a parameter: mail from a
+ * housing cooperative's system has to be attributable to the cooperative.
+ * Requires the mail:send permission.
+ */
+export interface PluginMail {
+    send(message: PluginMailMessage): Promise<void>;
+}
+export interface PluginSmsMessage {
+    /** The recipient's number in E.164 form. */
+    to: string;
+    /**
+     * The whole message, as text.
+     *
+     * SMS carries no markup, no subject and no alternative part, so what is
+     * written here is literally what the recipient reads. Its length is the
+     * plugin's own decision and is not bounded by the host: a text message is
+     * billed by length, and what a message may cost the association is the
+     * plugin's business to keep in hand rather than something a silent
+     * truncation can settle.
+     */
+    text: string;
+}
+/**
+ * Sends text messages through the instance's configured SMS provider.
+ *
+ * The sender the message presents is the instance's and is not a parameter,
+ * for the reason the mail from address is not one: a text message from a
+ * housing cooperative's system has to be attributable to the cooperative.
+ *
+ * An instance with no provider configured cannot send at all, and the send
+ * fails rather than being dropped. Having no provider is the ordinary state of
+ * a housing cooperative that only ever mails its members, so a plugin whose
+ * work depends on SMS should read `permissions` and degrade, or treat the
+ * failure as the answer. Requires the sms:send permission.
+ */
+export interface PluginSms {
+    send(message: PluginSmsMessage): Promise<void>;
+}
+/**
+ * Background work. Queue names are namespaced with the plugin's id by the
+ * host, so two plugins cannot collide on a name and no plugin can subscribe to
+ * a core queue. A name is 1-64 letters, digits, `_`, `.` or `-`; any other
+ * name is refused with a RangeError. Requires the jobs:schedule permission.
+ */
+export interface PluginJobs {
+    work<Data extends object>(name: string, handler: (data: Data) => Promise<void> | void): Promise<void>;
+    send<Data extends object>(name: string, data: Data): Promise<void>;
+    sendAt<Data extends object>(name: string, data: Data, runAt: Date): Promise<void>;
+    schedule<Data extends object>(name: string, cron: string, data: Data): Promise<void>;
+}
+export interface PluginApartment {
+    id: string;
+    number: string;
+    floor: number | null;
+    address: {
+        id: string;
+        street: string;
+        number: string;
+    };
+}
+export interface PluginResident {
+    personId: string;
+    name: string;
+    /** MEMBER holds the tenant-ownership; RESIDENT occupies without holding it. */
+    role: "MEMBER" | "RESIDENT";
+    apartment: PluginApartment | null;
+    movedInOn: string | null;
+    movedOutOn: string | null;
+    /** Present only with the addressBook:readContact permission. */
+    email?: string | null;
+    /** Present only with the addressBook:readContact permission. */
+    phone?: string | null;
+}
+export interface PluginOccupancySummary {
+    apartments: number;
+    /** Distinct persons with a current residency. */
+    residents: number;
+    /** Distinct persons holding a current tenant-ownership. */
+    members: number;
+}
+/**
+ * Reading the register, scoped to what the plugin declared.
+ *
+ * Three rules hold on every method here regardless of permission, because
+ * they are the product's own (plan section 4.4) and a plugin is not a reason
+ * to relax them: a person with protected personal data never appears, a
+ * personal identity number is never returned, and nothing is writable.
+ * Requires addressBook:read; the contact fields additionally require
+ * addressBook:readContact.
+ */
+export interface PluginAddressBook {
+    apartments(): Promise<PluginApartment[]>;
+    /** Current residencies only. Moved-out rows are not plugin business. */
+    residents(): Promise<PluginResident[]>;
+    summary(): Promise<PluginOccupancySummary>;
+}
+/**
+ * The host object a plugin's module factory receives.
+ *
+ * It is late-bound: the services behind it are the application's own, and the
+ * application is built after the factory has run. Every member below is
+ * therefore usable from a lifecycle hook (`onModuleInit` onwards), a guard or
+ * a request handler, and not from a provider's constructor - which is where
+ * NestJS asks for work to be done in any case. A call made too early throws
+ * rather than reading a half-built application.
+ *
+ * A plugin the board has switched off keeps its object, and every service on
+ * it refuses. Disabling has to bite immediately, and a plugin whose own timer
+ * outlived the switch must not still be reading the register through it.
+ */
+export interface PluginHost {
+    /** The plugin's own id, as declared in its manifest. */
+    id: string;
+    /** What the manifest declared and the board consented to. */
+    permissions: readonly PluginPermission[];
+    logger: PluginLogger;
+    settings: PluginSettings;
+    mail: PluginMail;
+    sms: PluginSms;
+    jobs: PluginJobs;
+    addressBook: PluginAddressBook;
+    /**
+     * The actions this plugin declared, and dispatch for every action it may
+     * reach.
+     *
+     * Added after this contract version shipped, so a plugin built against a
+     * newer host than the one it is installed on must feature-detect before
+     * using it - `isSupportedApiVersion` cannot see a member added to an
+     * interface, and the failure would otherwise surface as a load-failed
+     * finding with the message deliberately withheld.
+     */
+    actions: PluginActions;
+}
+/**
+ * A host service was used before the application finished starting, or after
+ * the plugin stopped serving.
+ *
+ * Both cases are the plugin reaching for the host at a moment the host cannot
+ * answer for: the first is work done in a constructor that belongs in
+ * `onModuleInit`, the second is a plugin the board switched off.
+ */
+export declare class PluginHostUnavailableError extends Error {
+    readonly pluginId: string;
+    readonly detail: string;
+    constructor(pluginId: string, detail: string);
+}
+//# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

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

package/dist/host.js

@@ -0,0 +1,41 @@
+/**
+ * The host services a plugin receives.
+ *
+ * Every service is present on the object whether or not the plugin declared
+ * the permission it needs; the ones it did not declare throw
+ * PluginPermissionError on use. Handing out nulls instead would push a
+ * null-check into every call site of a plugin that did declare the permission,
+ * for the sake of a case the plugin author has already ruled out by writing
+ * the manifest. `permissions` is on the object for the plugin that genuinely
+ * wants to degrade rather than fail.
+ */
+export class PluginPermissionError extends Error {
+    pluginId;
+    permission;
+    constructor(pluginId, permission) {
+        super(`Plugin "${pluginId}" used a service requiring the "${permission}" ` +
+            `permission, which its manifest does not declare.`);
+        this.pluginId = pluginId;
+        this.permission = permission;
+        this.name = "PluginPermissionError";
+    }
+}
+/**
+ * A host service was used before the application finished starting, or after
+ * the plugin stopped serving.
+ *
+ * Both cases are the plugin reaching for the host at a moment the host cannot
+ * answer for: the first is work done in a constructor that belongs in
+ * `onModuleInit`, the second is a plugin the board switched off.
+ */
+export class PluginHostUnavailableError extends Error {
+    pluginId;
+    detail;
+    constructor(pluginId, detail) {
+        super(`Plugin "${pluginId}" used a host service ${detail}`);
+        this.pluginId = pluginId;
+        this.detail = detail;
+        this.name = "PluginHostUnavailableError";
+    }
+}
+//# sourceMappingURL=host.js.map

package/dist/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAEnC,QAAQ;IACR,UAAU;IAFrB,YACW,QAAgB,EAChB,UAA4B;QAErC,KAAK,CACH,WAAW,QAAQ,mCAAmC,UAAU,IAAI;YAClE,kDAAkD,CACrD,CAAC;wBANO,QAAQ;0BACR,UAAU;QAMnB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAoMD;;;;;;;GAOG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAExC,QAAQ;IACR,MAAM;IAFjB,YACW,QAAgB,EAChB,MAAc;QAEvB,KAAK,CAAC,WAAW,QAAQ,yBAAyB,MAAM,EAAE,CAAC,CAAC;wBAHnD,QAAQ;sBACR,MAAM;QAGf,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @openbrf/plugin-sdk - the public plugin contract for Open BRF.
+ *
+ * A plugin depends on this package for types and for the manifest schema it
+ * validates itself against in its own CI. At runtime the host injects
+ * everything a plugin uses (see PluginHost), so nothing exported here needs to
+ * be resolvable from inside an installed plugin directory - which is what lets
+ * a plugin ship as a self-contained bundle (ADR 0003).
+ */
+export { ACTION_CHANNELS, ACTION_EFFECTS, ACTION_NAME_PATTERN, ACTION_PERSONAL_DATA, ACTION_SURFACES, type ActionChannel, type ActionClient, type ActionContext, type ActionDefinition, type ActionEffect, type ActionErrorSpec, type ActionPersonalData, type ActionPrincipal, type ActionRequest, type ActionSummary, type ActionSurface, type PluginActionFilter, type PluginActionRegistration, type PluginActions, } from "./actions.ts";
+export { actionInputJsonSchema, actionOutputJsonSchema, isHostZodSchema, } from "./action-schema.ts";
+export { isSupportedApiVersion, PLUGIN_API_VERSION, SUPPORTED_PLUGIN_API_VERSIONS, } from "./api-version.ts";
+export { type Catalog, type CatalogArtifact, catalogArtifactSchema, type CatalogEntry, catalogEntrySchema, type CatalogParseResult, type CatalogPluginEntry, catalogPluginEntrySchema, catalogSchema, type CatalogThemeEntry, catalogThemeEntrySchema, type LocalizedText, parseCatalogIndex, } from "./catalog.ts";
+export { definePlugin } from "./define-plugin.ts";
+export { formatSha512, IntegrityError, parseSha512 } from "./integrity.ts";
+export { PLUGIN_FINDING_REASONS, type PluginFindingDetail, type PluginFindingReason, } from "./findings.ts";
+export { type PluginAddressBook, type PluginApartment, type PluginHost, PluginHostUnavailableError, type PluginJobs, type PluginLogger, type PluginMail, type PluginMailMessage, type PluginOccupancySummary, PluginPermissionError, type PluginResident, type PluginSettings, type PluginSms, type PluginSmsMessage, } from "./host.ts";
+export type { PluginModuleFactory } from "./module.ts";
+export { assertPluginPackage, composedActionName, CURRENT_PLUGIN_API_VERSION, type ManifestParseResult, type PluginActionDeclaration, pluginActionSchema, pluginActionsSchema, type PluginEntry, pluginEntrySchema, pluginIdSchema, type PluginManifest, pluginManifestSchema, type PluginPackage, pluginPackageSchema, parsePluginPackage, } from "./manifest.ts";
+export { HOST_SHARED_PACKAGES, type PluginPackageContents, pluginPackageProblems, } from "./package-check.ts";
+export type { StandardSchemaIssue, StandardSchemaResult, StandardSchemaV1, } from "./standard-schema.ts";
+export { isPluginPermission, PLUGIN_PERMISSIONS, PLUGIN_PERSONAL_DATA_CATEGORIES, type PluginPermission, type PluginPersonalDataCategory, } from "./permissions.ts";
+export { defaultSettings, type PluginSettingsField, pluginSettingsFieldSchema, type PluginSettingsSchema, pluginSettingsSchema, type PluginSettingsValues, settingsValidator, } from "./settings-schema.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,6BAA6B,GAC9B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,eAAe,EACpB,qBAAqB,EACrB,KAAK,YAAY,EACjB,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,wBAAwB,EACxB,aAAa,EACb,KAAK,iBAAiB,EACtB,uBAAuB,EACvB,KAAK,aAAa,EAClB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EACL,sBAAsB,EACtB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,0BAA0B,EAC1B,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,0BAA0B,EAC1B,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,WAAW,EAChB,iBAAiB,EACjB,cAAc,EACd,KAAK,cAAc,EACnB,oBAAoB,EACpB,KAAK,aAAa,EAClB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,oBAAoB,EACpB,KAAK,qBAAqB,EAC1B,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,+BAA+B,EAC/B,KAAK,gBAAgB,EACrB,KAAK,0BAA0B,GAChC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,eAAe,EACf,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,KAAK,oBAAoB,EACzB,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * @openbrf/plugin-sdk - the public plugin contract for Open BRF.
+ *
+ * A plugin depends on this package for types and for the manifest schema it
+ * validates itself against in its own CI. At runtime the host injects
+ * everything a plugin uses (see PluginHost), so nothing exported here needs to
+ * be resolvable from inside an installed plugin directory - which is what lets
+ * a plugin ship as a self-contained bundle (ADR 0003).
+ */
+export { ACTION_CHANNELS, ACTION_EFFECTS, ACTION_NAME_PATTERN, ACTION_PERSONAL_DATA, ACTION_SURFACES, } from "./actions.js";
+export { actionInputJsonSchema, actionOutputJsonSchema, isHostZodSchema, } from "./action-schema.js";
+export { isSupportedApiVersion, PLUGIN_API_VERSION, SUPPORTED_PLUGIN_API_VERSIONS, } from "./api-version.js";
+export { catalogArtifactSchema, catalogEntrySchema, catalogPluginEntrySchema, catalogSchema, catalogThemeEntrySchema, parseCatalogIndex, } from "./catalog.js";
+export { definePlugin } from "./define-plugin.js";
+export { formatSha512, IntegrityError, parseSha512 } from "./integrity.js";
+export { PLUGIN_FINDING_REASONS, } from "./findings.js";
+export { PluginHostUnavailableError, PluginPermissionError, } from "./host.js";
+export { assertPluginPackage, composedActionName, CURRENT_PLUGIN_API_VERSION, pluginActionSchema, pluginActionsSchema, pluginEntrySchema, pluginIdSchema, pluginManifestSchema, pluginPackageSchema, parsePluginPackage, } from "./manifest.js";
+export { HOST_SHARED_PACKAGES, pluginPackageProblems, } from "./package-check.js";
+export { isPluginPermission, PLUGIN_PERMISSIONS, PLUGIN_PERSONAL_DATA_CATEGORIES, } from "./permissions.js";
+export { defaultSettings, pluginSettingsFieldSchema, pluginSettingsSchema, settingsValidator, } from "./settings-schema.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,GAehB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,6BAA6B,GAC9B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAGL,qBAAqB,EAErB,kBAAkB,EAGlB,wBAAwB,EACxB,aAAa,EAEb,uBAAuB,EAEvB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EACL,sBAAsB,GAGvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,0BAA0B,EAM1B,qBAAqB,GAKtB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,0BAA0B,EAG1B,kBAAkB,EAClB,mBAAmB,EAEnB,iBAAiB,EACjB,cAAc,EAEd,oBAAoB,EAEpB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,oBAAoB,EAEpB,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAM5B,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,+BAA+B,GAGhC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,eAAe,EAEf,yBAAyB,EAEzB,oBAAoB,EAEpB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC"}

package/dist/integrity.d.ts

@@ -0,0 +1,38 @@
+/**
+ * How a catalog entry spells the sha512 digest of its tarball.
+ *
+ * The instance verifies the digest before it unpacks a download, and the
+ * catalog's own check verifies it before a listing is merged. Both must accept
+ * exactly the same spellings, or the catalog passes an entry the instance then
+ * refuses. So the parsing lives here, in the contract both depend on, and
+ * nowhere else.
+ *
+ * Written without `Buffer` or `node:crypto`: this package is also bundled into
+ * apps/web, a browser, where neither exists, and hashing itself stays with the
+ * caller. Base64 is decoded by hand rather than with `atob` so that padding and
+ * stray trailing bits are read as `Buffer` reads them, whatever the runtime.
+ */
+/**
+ * Why a digest was refused. `malformed-digest` is a catalog entry that is
+ * written wrongly; `digest-mismatch` is bytes that are not the ones the entry
+ * names. Installers branch on the difference.
+ */
+export declare class IntegrityError extends Error {
+    readonly reason: "malformed-digest" | "digest-mismatch";
+    constructor(message: string, reason: "malformed-digest" | "digest-mismatch");
+}
+/**
+ * Normalizes a declared digest to raw bytes.
+ *
+ * Both spellings are accepted because both are what a publisher actually has
+ * to hand: `npm pack --json` reports the subresource-integrity form
+ * (`sha512-<base64>`), while `sha512sum` prints hex. Requiring one would mean
+ * every catalog entry is transcribed by hand from the other, which is how a
+ * digest ends up wrong in a way nobody notices until an install fails.
+ *
+ * @throws IntegrityError with reason `malformed-digest`.
+ */
+export declare function parseSha512(declared: string): Uint8Array;
+/** The subresource-integrity spelling, which is what a catalog entry carries. */
+export declare function formatSha512(digest: Uint8Array): string;
+//# sourceMappingURL=integrity.d.ts.map

package/dist/integrity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrity.d.ts","sourceRoot":"","sources":["../src/integrity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;IAGrC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,GAAG,iBAAiB;IAFzD,YACE,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,kBAAkB,GAAG,iBAAiB,EAIxD;CACF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAuBxD;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAEvD"}

package/dist/integrity.js

@@ -0,0 +1,105 @@
+/**
+ * How a catalog entry spells the sha512 digest of its tarball.
+ *
+ * The instance verifies the digest before it unpacks a download, and the
+ * catalog's own check verifies it before a listing is merged. Both must accept
+ * exactly the same spellings, or the catalog passes an entry the instance then
+ * refuses. So the parsing lives here, in the contract both depend on, and
+ * nowhere else.
+ *
+ * Written without `Buffer` or `node:crypto`: this package is also bundled into
+ * apps/web, a browser, where neither exists, and hashing itself stays with the
+ * caller. Base64 is decoded by hand rather than with `atob` so that padding and
+ * stray trailing bits are read as `Buffer` reads them, whatever the runtime.
+ */
+const SRI_PATTERN = /^sha512-([A-Za-z0-9+/]+)={0,2}$/;
+const HEX_PATTERN = /^[0-9a-f]{128}$/i;
+const SHA512_BYTES = 64;
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/**
+ * Why a digest was refused. `malformed-digest` is a catalog entry that is
+ * written wrongly; `digest-mismatch` is bytes that are not the ones the entry
+ * names. Installers branch on the difference.
+ */
+export class IntegrityError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "IntegrityError";
+    }
+}
+/**
+ * Normalizes a declared digest to raw bytes.
+ *
+ * Both spellings are accepted because both are what a publisher actually has
+ * to hand: `npm pack --json` reports the subresource-integrity form
+ * (`sha512-<base64>`), while `sha512sum` prints hex. Requiring one would mean
+ * every catalog entry is transcribed by hand from the other, which is how a
+ * digest ends up wrong in a way nobody notices until an install fails.
+ *
+ * @throws IntegrityError with reason `malformed-digest`.
+ */
+export function parseSha512(declared) {
+    const trimmed = declared.trim();
+    const sri = SRI_PATTERN.exec(trimmed);
+    if (sri !== null) {
+        const bytes = fromBase64(sri[1] ?? "");
+        if (bytes.length !== SHA512_BYTES) {
+            throw new IntegrityError("A sha512 digest is 64 bytes; this one is not.", "malformed-digest");
+        }
+        return bytes;
+    }
+    if (HEX_PATTERN.test(trimmed)) {
+        return fromHex(trimmed);
+    }
+    throw new IntegrityError('Expected a digest written as "sha512-<base64>" or 128 hex characters.', "malformed-digest");
+}
+/** The subresource-integrity spelling, which is what a catalog entry carries. */
+export function formatSha512(digest) {
+    return `sha512-${toBase64(digest)}`;
+}
+function fromHex(hex) {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let index = 0; index < bytes.length; index += 1) {
+        bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+    }
+    return bytes;
+}
+/**
+ * Standard base64 without its padding, which the caller has already split off.
+ * Stray trailing bits are dropped, as `Buffer.from(_, "base64")` drops them.
+ */
+function fromBase64(characters) {
+    const bytes = new Uint8Array(Math.floor((characters.length * 6) / 8));
+    let accumulator = 0;
+    let bits = 0;
+    let written = 0;
+    for (const character of characters) {
+        accumulator = (accumulator << 6) | BASE64_ALPHABET.indexOf(character);
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            bytes[written] = (accumulator >> bits) & 0xff;
+            written += 1;
+            accumulator &= (1 << bits) - 1;
+        }
+    }
+    return bytes;
+}
+function toBase64(bytes) {
+    let encoded = "";
+    for (let index = 0; index < bytes.length; index += 3) {
+        const first = bytes[index] ?? 0;
+        const second = bytes[index + 1] ?? 0;
+        const third = bytes[index + 2] ?? 0;
+        const group = (first << 16) | (second << 8) | third;
+        const remaining = bytes.length - index;
+        encoded += BASE64_ALPHABET.charAt((group >> 18) & 63);
+        encoded += BASE64_ALPHABET.charAt((group >> 12) & 63);
+        encoded += remaining > 1 ? BASE64_ALPHABET.charAt((group >> 6) & 63) : "=";
+        encoded += remaining > 2 ? BASE64_ALPHABET.charAt(group & 63) : "=";
+    }
+    return encoded;
+}
+//# sourceMappingURL=integrity.js.map

package/dist/integrity.js.map

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