@cervio/plugin-core 0.1.1 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Cervio S.r.l.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -15,6 +15,6 @@ const fields = parseManifestObject(manifestJson)
 const packed = await packPlugin({ dir: '.' })
 ```
 
-See docs at `docs.cervio.app` (when deployed) and `docs/plugins/AUTHORING.md` in the Cervio repo.
+See docs at `docs.cervio.app` (when deployed) and [Authoring](https://docs.cervio.app/docs/authoring) in the Cervio repo.
 
 **Versioning note:** this package version is independent of plugin release versions (assigned by the host) and of `@cervio/plugin-sdk` (tracks CervioUI API).

package/dist/browser-Ddj__JFI.d.ts

@@ -0,0 +1,141 @@
+/**
+ * `boot_requests` in manifest.json: GET calls the plugin makes as soon as it
+ * starts. The host starts them itself while the plugin is still loading, and
+ * the plugin's own `fetch` of the same path + query is answered from that
+ * response (once) instead of waiting for a new round trip. Pure hint: a plugin
+ * that never asks gets nothing extra, and any other request works as before.
+ *
+ * Example: `{ "path": "/api/v1/entities/attivita/records?limit=200" }`.
+ * `/api/v1/entities/<technical name>/...` is accepted: the host also matches
+ * the same path with the entity id the plugin may use.
+ */
+type PluginBootRequest = {
+    /** Absolute path + optional query under `/api/v1/`, e.g. `/api/v1/entities/x/records?limit=50`. */
+    path: string;
+};
+/** Lenient read of the stored snapshot (`installed_plugins.declared_boot_requests`). */
+declare function parsePluginBootRequests(raw: unknown): PluginBootRequest[];
+
+/** Canonical Policy Plugin type is `policy`; `server` is a silent legacy alias. */
+type PluginType = 'task' | 'form' | 'task_form' | 'route' | 'policy' | 'server';
+type PluginActionResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+interface ParsedPluginManifest {
+    pluginKey: string;
+    pluginName: string | null;
+    pluginType: PluginType | null;
+    /** Present in ZIP but ignored for assignment; Cervio owns release versions. */
+    manifestVersion: string | null;
+    /** Catalog capability ids the plugin needs (e.g. calendar). */
+    requiredConnectionCapabilities: string[];
+    /** External Connections requirements (OAuth broker). */
+    connections: PluginConnectionRequirement[];
+    /** Declared Cervio entity deps (name-based; for Admin + future export). */
+    entities: PluginEntityRequirement[];
+    /** Declared Cervio API path prefixes — fetch relay allowlist (fail-closed if empty). */
+    cervioApis: PluginCervioApiRequirement[];
+    /** Declared Admin-editable settings fields (drives Impostazioni dynamic form). */
+    settings: PluginSettingsFieldRequirement[];
+    /** GET calls the host prefetches while the plugin loads (`boot_requests`). */
+    bootRequests: PluginBootRequest[];
+    artifactEntryPath: string;
+    rawManifest: Record<string, unknown>;
+    manifestEntryName: string;
+}
+type PluginEntityAccess = 'read' | 'write';
+type PluginEntityRequirement = {
+    name: string;
+    fields: string[];
+    forms: string[];
+    access: PluginEntityAccess[];
+};
+type PluginCervioApiRequirement = {
+    method: string;
+    path_prefix: string;
+};
+type PluginSettingsFieldType = 'string' | 'boolean' | 'select' | 'multiselect';
+type PluginSettingsFieldOption = {
+    value: string;
+    label: string;
+};
+type PluginSettingsFieldRequirement = {
+    key: string;
+    type: PluginSettingsFieldType;
+    label: string;
+    hint?: string;
+    placeholder?: string;
+    default?: string | boolean | string[];
+    /** Required for `select` / `multiselect`. */
+    options?: PluginSettingsFieldOption[];
+};
+type ExternalConnectionHttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+type AllowedApiRule = {
+    host: string;
+    methods: ExternalConnectionHttpMethod[];
+    path_prefix: string;
+};
+type PluginConnectionRequirement = {
+    id: string;
+    provider: string;
+    consent: 'user';
+    scopes: string[];
+    allowed_apis: AllowedApiRule[];
+};
+type ParseManifestOptions = {
+    /**
+     * Capability ids a plugin may declare in `required_connection_capabilities`.
+     * Host passes the live catalog; CLI uses {@link DEFAULT_PLUGIN_DECLARABLE_CAPABILITIES}.
+     */
+    allowedCapabilities?: readonly string[];
+};
+declare const MAX_PLUGIN_ZIP_BYTES: number;
+declare const MAX_PLUGIN_ZIP_ENTRIES = 5000;
+declare const MAX_PLUGIN_UNCOMPRESSED_BYTES: number;
+/** Soft UX budget (warn) — not a hard reject. */
+declare const PLUGIN_ARTIFACT_SOFT_WARN_BYTES: number;
+/** Soft UX budget (strong warn) — not a hard reject. */
+declare const PLUGIN_ARTIFACT_SOFT_STRONG_WARN_BYTES: number;
+declare const PLUGIN_KEY_RE: RegExp;
+/**
+ * Static default for CLI validate. Generated from host `CONNECTION_CAPABILITY_CATALOG`
+ * where `pluginDeclarable === true`. Guarded by drift test against the host catalog.
+ */
+declare const DEFAULT_PLUGIN_DECLARABLE_CAPABILITIES: readonly ["calendar"];
+
+/** A plugin ZIP that passed the safety checks, with its files inflated in memory. */
+interface PluginZip {
+    /** File paths (directories excluded), as stored in the archive. */
+    readonly paths: readonly string[];
+    /** Bytes of a file, or `undefined` when the archive has no such file. */
+    bytes(path: string): Uint8Array | undefined;
+    /** UTF-8 text of a file, or `undefined` when the archive has no such file. */
+    text(path: string): string | undefined;
+}
+/**
+ * Opens a plugin ZIP safely. Entry count, paths, nested archives, declared sizes
+ * and compression ratios are checked from the headers before any entry is
+ * inflated; the inflated total is checked again, so an archive that understates
+ * its sizes is still rejected. The only way to read a plugin ZIP: there is no
+ * unchecked variant.
+ */
+declare function readPluginZip(data: ArrayBuffer | Uint8Array): Promise<PluginActionResult<PluginZip>>;
+/** Cheap pre-check on an uploaded file before reading it: extension and size. */
+declare function assertZipFile(file: {
+    name?: string;
+    size: number;
+}): PluginActionResult<true>;
+
+/** Parse `entities` from manifest.json (invalid entries skipped). */
+declare function parsePluginEntityRequirements(raw: unknown): PluginEntityRequirement[];
+declare function isDeclarableCervioApiRequirement(row: PluginCervioApiRequirement): boolean;
+declare function isDeclaredCervioApiRequest(method: string, pathname: string, declared: readonly PluginCervioApiRequirement[]): boolean;
+/** Parse `cervio_apis` from manifest.json (skips malformed rows; does not enforce declarable paths). */
+declare function parsePluginCervioApiRequirements(raw: unknown): PluginCervioApiRequirement[];
+
+export { DEFAULT_PLUGIN_DECLARABLE_CAPABILITIES as D, MAX_PLUGIN_UNCOMPRESSED_BYTES as M, MAX_PLUGIN_ZIP_BYTES as j, MAX_PLUGIN_ZIP_ENTRIES as k, PLUGIN_ARTIFACT_SOFT_STRONG_WARN_BYTES as l, PLUGIN_ARTIFACT_SOFT_WARN_BYTES as m, PLUGIN_KEY_RE as n, assertZipFile as r, isDeclarableCervioApiRequirement as s, isDeclaredCervioApiRequest as t, parsePluginBootRequests as u, parsePluginCervioApiRequirements as v, parsePluginEntityRequirements as w, readPluginZip as x };
+export type { AllowedApiRule as A, ExternalConnectionHttpMethod as E, ParseManifestOptions as P, PluginActionResult as a, PluginType as b, PluginConnectionRequirement as c, PluginEntityRequirement as d, PluginCervioApiRequirement as e, PluginSettingsFieldRequirement as f, PluginBootRequest as g, ParsedPluginManifest as h, PluginZip as i, PluginEntityAccess as o, PluginSettingsFieldOption as p, PluginSettingsFieldType as q };

package/dist/browser.d.ts

@@ -0,0 +1 @@
+export { M as MAX_PLUGIN_UNCOMPRESSED_BYTES, j as MAX_PLUGIN_ZIP_BYTES, k as MAX_PLUGIN_ZIP_ENTRIES, a as PluginActionResult, g as PluginBootRequest, e as PluginCervioApiRequirement, i as PluginZip, r as assertZipFile, s as isDeclarableCervioApiRequirement, t as isDeclaredCervioApiRequest, u as parsePluginBootRequests, v as parsePluginCervioApiRequirements, x as readPluginZip } from './browser-Ddj__JFI.js';

package/dist/browser.js

@@ -0,0 +1,166 @@
+import { unzipSync, strFromU8 } from 'fflate';
+
+// src/zip-safety.ts
+
+// src/types.ts
+var MAX_PLUGIN_ZIP_BYTES = 50 * 1024 * 1024;
+var MAX_PLUGIN_ZIP_ENTRIES = 5e3;
+var MAX_PLUGIN_UNCOMPRESSED_BYTES = 250 * 1024 * 1024;
+
+// src/zip-safety.ts
+var MAX_COMPRESSION_RATIO = 100;
+var RATIO_CHECK_FROM_BYTES = 1024 * 1024;
+function checkEntry(entry) {
+  const { name, size, originalSize } = entry;
+  if (name.includes("..") || name.includes("\\") || name.startsWith("/")) {
+    return "zip_unsafe_entry_path";
+  }
+  if (/\.zip$/i.test(name)) return "zip_nested_archive";
+  if (originalSize > RATIO_CHECK_FROM_BYTES) {
+    if (size === 0 || originalSize / size > MAX_COMPRESSION_RATIO) {
+      return "zip_compression_ratio_too_high";
+    }
+  }
+  return null;
+}
+async function readPluginZip(data) {
+  const input = data instanceof Uint8Array ? data : new Uint8Array(data);
+  if (input.byteLength > MAX_PLUGIN_ZIP_BYTES) return { ok: false, error: "file_too_large" };
+  let error = null;
+  let entries = 0;
+  let declaredTotal = 0;
+  let files;
+  try {
+    files = unzipSync(input, {
+      filter: (entry) => {
+        if (error) return false;
+        entries += 1;
+        if (entries > MAX_PLUGIN_ZIP_ENTRIES) {
+          error = "zip_too_many_entries";
+          return false;
+        }
+        error = checkEntry(entry);
+        if (error) return false;
+        if (entry.name.endsWith("/")) return false;
+        declaredTotal += entry.originalSize;
+        if (declaredTotal > MAX_PLUGIN_UNCOMPRESSED_BYTES) {
+          error = "zip_uncompressed_too_large";
+          return false;
+        }
+        return true;
+      }
+    });
+  } catch {
+    files = null;
+  }
+  if (error) return { ok: false, error };
+  if (!files) return { ok: false, error: "zip_invalid" };
+  let actualTotal = 0;
+  for (const bytes of Object.values(files)) actualTotal += bytes.byteLength;
+  if (actualTotal > MAX_PLUGIN_UNCOMPRESSED_BYTES) {
+    return { ok: false, error: "zip_uncompressed_too_large" };
+  }
+  const paths = Object.keys(files);
+  return {
+    ok: true,
+    value: {
+      paths,
+      bytes: (path) => files[path],
+      text: (path) => {
+        const bytes = files[path];
+        return bytes === void 0 ? void 0 : strFromU8(bytes);
+      }
+    }
+  };
+}
+function assertZipFile(file) {
+  const name = (file.name ?? "upload.zip").toLowerCase();
+  if (!name.endsWith(".zip")) return { ok: false, error: "invalid_file_extension" };
+  if (file.size <= 0) return { ok: false, error: "empty_file" };
+  if (file.size > MAX_PLUGIN_ZIP_BYTES) return { ok: false, error: "file_too_large" };
+  return { ok: true, value: true };
+}
+
+// src/entity-requirements.ts
+var HTTP_METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "*"]);
+var DECLARABLE_HTTP_METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
+var CERVIO_API_PREFIX = "/api/v1/";
+var MAX_CERVIO_API_PREFIX_LEN = 256;
+var CERVIO_API_PREFIX_SAFE_RE = /^\/api\/v1\/[a-zA-Z0-9][a-zA-Z0-9._/-]{0,253}$/;
+function readCervioApiPath(row) {
+  return typeof row.path_prefix === "string" ? row.path_prefix.trim() : typeof row.pathPrefix === "string" ? row.pathPrefix.trim() : "";
+}
+function isDeclarableCervioApiPrefix(path) {
+  if (!path.startsWith(CERVIO_API_PREFIX)) return false;
+  if (path.length > MAX_CERVIO_API_PREFIX_LEN) return false;
+  if (path.includes("..") || path.includes("//") || path.includes("\\") || path.includes("*") || path.includes("?")) {
+    return false;
+  }
+  if (!CERVIO_API_PREFIX_SAFE_RE.test(path.replace(/\/$/, "") || path)) return false;
+  const rest = path.slice(CERVIO_API_PREFIX.length);
+  const firstSeg = rest.split("/").filter(Boolean)[0]?.toLowerCase();
+  if (!firstSeg) return false;
+  if (firstSeg === "admin") return false;
+  return true;
+}
+function isDeclarableCervioApiRequirement(row) {
+  return DECLARABLE_HTTP_METHODS.has(row.method.toUpperCase()) && isDeclarableCervioApiPrefix(row.path_prefix);
+}
+function pathMatchesCervioApiPrefix(pathname, prefix) {
+  if (!prefix.startsWith("/") || prefix.includes("..") || prefix.includes("//")) return false;
+  if (pathname === prefix) return true;
+  if (prefix.endsWith("/")) return pathname.startsWith(prefix);
+  return pathname.startsWith(`${prefix}/`);
+}
+function isDeclaredCervioApiRequest(method, pathname, declared) {
+  const m = method.trim().toUpperCase();
+  if (!declared.length) return false;
+  for (const row of declared) {
+    const declaredMethod = row.method.trim().toUpperCase();
+    const methodOk = declaredMethod === m || declaredMethod === "*" || m === "HEAD" && declaredMethod === "GET";
+    if (!methodOk) continue;
+    if (pathMatchesCervioApiPrefix(pathname, row.path_prefix)) return true;
+  }
+  return false;
+}
+function parsePluginCervioApiRequirements(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of raw) {
+    if (!item || typeof item !== "object") continue;
+    const row = item;
+    const methodRaw = typeof row.method === "string" ? row.method.trim().toUpperCase() : "GET";
+    const method = HTTP_METHODS.has(methodRaw) ? methodRaw : "GET";
+    const path = readCervioApiPath(row);
+    if (!path || !path.startsWith("/")) continue;
+    const key = `${method}:${path}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ method, path_prefix: path });
+  }
+  return out;
+}
+
+// src/boot-requests.ts
+var MAX_PLUGIN_BOOT_REQUESTS = 8;
+var MAX_BOOT_PATH_LEN = 400;
+function bootRequestPathname(path) {
+  if (typeof path !== "string") return null;
+  const p = path.trim();
+  if (!p.startsWith("/api/v1/") || p.length > MAX_BOOT_PATH_LEN || p.includes("#")) return null;
+  const pathname = p.split("?")[0] ?? "";
+  if (!isDeclarableCervioApiPrefix(pathname)) return null;
+  return pathname;
+}
+function parsePluginBootRequests(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const item of raw.slice(0, MAX_PLUGIN_BOOT_REQUESTS)) {
+    const path = item && typeof item === "object" ? item.path : void 0;
+    if (typeof path === "string" && bootRequestPathname(path)) out.push({ path: path.trim() });
+  }
+  return out;
+}
+
+export { MAX_PLUGIN_UNCOMPRESSED_BYTES, MAX_PLUGIN_ZIP_BYTES, MAX_PLUGIN_ZIP_ENTRIES, assertZipFile, isDeclarableCervioApiRequirement, isDeclaredCervioApiRequest, parsePluginBootRequests, parsePluginCervioApiRequirements, readPluginZip };