@cervio/plugin-core 0.1.0 → 0.1.4

package/dist/index.d.cts

@@ -1,92 +1,16 @@
-import JSZip from 'jszip';
+import { P as PluginCervioApiRequirement, a as PluginEntityRequirement, b as PluginSettingsFieldRequirement, c as PluginConnectionRequirement, d as PluginActionResult, e as ParseManifestOptions, f as PluginType, g as ParsedPluginManifest } from './browser-CbWn_0Kk.cjs';
+export { A as AllowedApiRule, D as DEFAULT_PLUGIN_DECLARABLE_CAPABILITIES, E as ExternalConnectionHttpMethod, M as MAX_PLUGIN_UNCOMPRESSED_BYTES, h as MAX_PLUGIN_ZIP_BYTES, i as MAX_PLUGIN_ZIP_ENTRIES, j as PLUGIN_ARTIFACT_BUCKET, k as PLUGIN_KEY_RE, l as PLUGIN_VERSION_SELECT, m as PluginEntityAccess, n as PluginSettingsFieldOption, o as PluginSettingsFieldType, p as PluginVersionRow, q as assertZipFile, r as assertZipSafe } from './browser-CbWn_0Kk.cjs';
 import { z } from 'zod';
-
-type PluginType = 'task' | 'form' | 'task_form' | 'route';
-type PluginActionResult<T> = {
-    ok: true;
-    value: T;
-} | {
-    ok: false;
-    error: string;
-};
-interface PluginVersionRow {
-    id: string;
-    plugin_id: string;
-    version: string;
-    changelog: string | null;
-    artifact_path: string;
-    artifact_entry_path?: string | null;
-    artifact_sha256: string;
-    content_sha256?: string | null;
-    artifact_size_bytes: number;
-    created_at: 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 (documentation / future allowlist). */
-    cervioApis: PluginCervioApiRequirement[];
-    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 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 PLUGIN_ARTIFACT_BUCKET = "plugin-artifacts";
-declare const MAX_PLUGIN_ZIP_BYTES: number;
-declare const MAX_PLUGIN_ZIP_ENTRIES = 5000;
-declare const MAX_PLUGIN_UNCOMPRESSED_BYTES: number;
-declare const PLUGIN_KEY_RE: RegExp;
-declare const PLUGIN_VERSION_SELECT = "id, plugin_id, version, changelog, artifact_path, artifact_entry_path, artifact_sha256, content_sha256, artifact_size_bytes, created_at";
-/**
- * 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"];
+import JSZip from 'jszip';
 
 /** Parse `entities` from manifest.json (invalid entries skipped). */
 declare function parsePluginEntityRequirements(raw: unknown): PluginEntityRequirement[];
 /** Parse `cervio_apis` from manifest.json. */
 declare function parsePluginCervioApiRequirements(raw: unknown): PluginCervioApiRequirement[];
 
+/** Parse `settings` from manifest.json (invalid entries skipped). */
+declare function parsePluginSettingsRequirements(raw: unknown): PluginSettingsFieldRequirement[];
+
 declare const EXTERNAL_CONNECTION_ALLOWED_HOSTS: Record<string, readonly string[]>;
 declare const EXTERNAL_CONNECTION_HTTP_METHODS: readonly ["GET", "POST", "PATCH", "PUT", "DELETE"];
 declare const OAUTH_PROVIDER_KEY_RE: RegExp;
@@ -96,17 +20,6 @@ declare function isExternalConnectionProvider(v: string): boolean;
 /** Parse manifest `connections` array; drops invalid entries. */
 declare function parsePluginConnections(raw: unknown): PluginConnectionRequirement[];
 
-/**
- * Validates a loaded plugin ZIP before any entry is inflated (CERVIO-SEC-014):
- * caps the entry count and total declared uncompressed size to stop zip bombs,
- * and rejects path-traversal / absolute entry names as defense-in-depth.
- */
-declare function assertZipSafe(zip: JSZip): PluginActionResult<true>;
-declare function assertZipFile(file: {
-    name?: string;
-    size: number;
-}): PluginActionResult<true>;
-
 /**
  * Next patch version assigned by Cervio. Ignores pre-release/build metadata on
  * the previous label and bumps the patch component only.
@@ -121,9 +34,28 @@ declare const pluginManifestZodSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     plugin_name: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodString>;
-    plugin_type: z.ZodOptional<z.ZodEnum<["task", "form", "task_form", "route"]>>;
+    plugin_type: z.ZodOptional<z.ZodEnum<["task", "form", "task_form", "route", "policy", "server"]>>;
     kind: z.ZodOptional<z.ZodString>;
     version: z.ZodOptional<z.ZodString>;
+    hooks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        event: z.ZodEnum<["before_create", "before_update"]>;
+        entities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        blocking: z.ZodOptional<z.ZodBoolean>;
+        identity: z.ZodOptional<z.ZodEnum<["caller", "plugin_principal"]>>;
+        entry: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        event: "before_create" | "before_update";
+        entities?: string[] | undefined;
+        blocking?: boolean | undefined;
+        identity?: "caller" | "plugin_principal" | undefined;
+        entry?: string | undefined;
+    }, {
+        event: "before_create" | "before_update";
+        entities?: string[] | undefined;
+        blocking?: boolean | undefined;
+        identity?: "caller" | "plugin_principal" | undefined;
+        entry?: string | undefined;
+    }>, "many">>;
     required_connection_capabilities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     requiredConnectionCapabilities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     connections: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -200,14 +132,73 @@ declare const pluginManifestZodSchema: z.ZodObject<{
         pathPrefix?: string | undefined;
     }>, "many">>;
     cervioApis: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+    settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        type: z.ZodEnum<["string", "boolean", "select", "multiselect"]>;
+        label: z.ZodString;
+        hint: z.ZodOptional<z.ZodString>;
+        placeholder: z.ZodOptional<z.ZodString>;
+        default: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>>;
+        options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            label: string;
+        }, {
+            value: string;
+            label: string;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        label: string;
+        key: string;
+        type: "string" | "boolean" | "select" | "multiselect";
+        options?: {
+            value: string;
+            label: string;
+        }[] | undefined;
+        hint?: string | undefined;
+        placeholder?: string | undefined;
+        default?: string | boolean | string[] | undefined;
+    }, {
+        label: string;
+        key: string;
+        type: "string" | "boolean" | "select" | "multiselect";
+        options?: {
+            value: string;
+            label: string;
+        }[] | undefined;
+        hint?: string | undefined;
+        placeholder?: string | undefined;
+        default?: string | boolean | string[] | undefined;
+    }>, "many">>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     plugin_key: z.ZodOptional<z.ZodString>;
     id: z.ZodOptional<z.ZodString>;
     plugin_name: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodString>;
-    plugin_type: z.ZodOptional<z.ZodEnum<["task", "form", "task_form", "route"]>>;
+    plugin_type: z.ZodOptional<z.ZodEnum<["task", "form", "task_form", "route", "policy", "server"]>>;
     kind: z.ZodOptional<z.ZodString>;
     version: z.ZodOptional<z.ZodString>;
+    hooks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        event: z.ZodEnum<["before_create", "before_update"]>;
+        entities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        blocking: z.ZodOptional<z.ZodBoolean>;
+        identity: z.ZodOptional<z.ZodEnum<["caller", "plugin_principal"]>>;
+        entry: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        event: "before_create" | "before_update";
+        entities?: string[] | undefined;
+        blocking?: boolean | undefined;
+        identity?: "caller" | "plugin_principal" | undefined;
+        entry?: string | undefined;
+    }, {
+        event: "before_create" | "before_update";
+        entities?: string[] | undefined;
+        blocking?: boolean | undefined;
+        identity?: "caller" | "plugin_principal" | undefined;
+        entry?: string | undefined;
+    }>, "many">>;
     required_connection_capabilities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     requiredConnectionCapabilities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     connections: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -284,14 +275,73 @@ declare const pluginManifestZodSchema: z.ZodObject<{
         pathPrefix?: string | undefined;
     }>, "many">>;
     cervioApis: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+    settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        type: z.ZodEnum<["string", "boolean", "select", "multiselect"]>;
+        label: z.ZodString;
+        hint: z.ZodOptional<z.ZodString>;
+        placeholder: z.ZodOptional<z.ZodString>;
+        default: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>>;
+        options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            label: string;
+        }, {
+            value: string;
+            label: string;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        label: string;
+        key: string;
+        type: "string" | "boolean" | "select" | "multiselect";
+        options?: {
+            value: string;
+            label: string;
+        }[] | undefined;
+        hint?: string | undefined;
+        placeholder?: string | undefined;
+        default?: string | boolean | string[] | undefined;
+    }, {
+        label: string;
+        key: string;
+        type: "string" | "boolean" | "select" | "multiselect";
+        options?: {
+            value: string;
+            label: string;
+        }[] | undefined;
+        hint?: string | undefined;
+        placeholder?: string | undefined;
+        default?: string | boolean | string[] | undefined;
+    }>, "many">>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     plugin_key: z.ZodOptional<z.ZodString>;
     id: z.ZodOptional<z.ZodString>;
     plugin_name: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodString>;
-    plugin_type: z.ZodOptional<z.ZodEnum<["task", "form", "task_form", "route"]>>;
+    plugin_type: z.ZodOptional<z.ZodEnum<["task", "form", "task_form", "route", "policy", "server"]>>;
     kind: z.ZodOptional<z.ZodString>;
     version: z.ZodOptional<z.ZodString>;
+    hooks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        event: z.ZodEnum<["before_create", "before_update"]>;
+        entities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        blocking: z.ZodOptional<z.ZodBoolean>;
+        identity: z.ZodOptional<z.ZodEnum<["caller", "plugin_principal"]>>;
+        entry: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        event: "before_create" | "before_update";
+        entities?: string[] | undefined;
+        blocking?: boolean | undefined;
+        identity?: "caller" | "plugin_principal" | undefined;
+        entry?: string | undefined;
+    }, {
+        event: "before_create" | "before_update";
+        entities?: string[] | undefined;
+        blocking?: boolean | undefined;
+        identity?: "caller" | "plugin_principal" | undefined;
+        entry?: string | undefined;
+    }>, "many">>;
     required_connection_capabilities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     requiredConnectionCapabilities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     connections: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -368,9 +418,115 @@ declare const pluginManifestZodSchema: z.ZodObject<{
         pathPrefix?: string | undefined;
     }>, "many">>;
     cervioApis: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+    settings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        type: z.ZodEnum<["string", "boolean", "select", "multiselect"]>;
+        label: z.ZodString;
+        hint: z.ZodOptional<z.ZodString>;
+        placeholder: z.ZodOptional<z.ZodString>;
+        default: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>>;
+        options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            label: string;
+        }, {
+            value: string;
+            label: string;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        label: string;
+        key: string;
+        type: "string" | "boolean" | "select" | "multiselect";
+        options?: {
+            value: string;
+            label: string;
+        }[] | undefined;
+        hint?: string | undefined;
+        placeholder?: string | undefined;
+        default?: string | boolean | string[] | undefined;
+    }, {
+        label: string;
+        key: string;
+        type: "string" | "boolean" | "select" | "multiselect";
+        options?: {
+            value: string;
+            label: string;
+        }[] | undefined;
+        hint?: string | undefined;
+        placeholder?: string | undefined;
+        default?: string | boolean | string[] | undefined;
+    }>, "many">>;
 }, z.ZodTypeAny, "passthrough">>;
 type PluginManifestZod = z.infer<typeof pluginManifestZodSchema>;
 
+/**
+ * Policy Plugin hook contract (shared by host, SDK, and manifest authors).
+ * Wire legacy: `plugin_type: "server"` is an alias for `"policy"`.
+ */
+type PolicyHookEvent = 'before_create' | 'before_update';
+type PolicyHookCaller = {
+    userId?: string;
+    channel?: string;
+    organizationId?: string;
+};
+type PolicyHookInput = {
+    event: PolicyHookEvent;
+    entity: {
+        id?: string;
+        name?: string;
+    };
+    record: {
+        id?: string | null;
+        data: Record<string, unknown>;
+        previousData?: Record<string, unknown> | null;
+    };
+    caller?: PolicyHookCaller;
+    settings?: Record<string, unknown>;
+    pluginKey?: string;
+    allowedEntityReads?: string[];
+    deadlineMs?: number;
+};
+type PolicyHookResult = {
+    allow: true;
+} | {
+    allow: false;
+    message: string;
+    code?: string;
+};
+/** Host-mediated reads injected by plugin-sandbox-runner (null if no allowlist/caller). */
+type PolicyHost = {
+    getRecord(entityName: string, id: string): Promise<{
+        id: string;
+        data: Record<string, unknown>;
+    } | null>;
+    listRecords(entityName: string, opts?: {
+        filters?: Record<string, unknown>;
+        limit?: number;
+        offset?: number;
+    }): Promise<Array<{
+        id: string;
+        data: Record<string, unknown>;
+    }>>;
+    sumField(entityName: string, fieldName: string, opts?: {
+        filters?: Record<string, unknown>;
+    }): Promise<number>;
+};
+/** True for canonical `policy` and legacy wire `server`. */
+declare function isPolicyPluginType(t: string | null | undefined): boolean;
+/** Canonical type written on upload / preferred in new manifests. */
+declare function normalizeToPolicyPluginType(t: string | null | undefined): 'policy' | null;
+
+declare function findBareModuleSpecifiers(source: string): string[];
+declare function assertPolicyEntrySelfContained(source: string): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+    specifiers: string[];
+};
+
 declare function normalizePluginKey(raw: string): string;
 declare function parseManifestObject(parsed: Record<string, unknown>, options?: ParseManifestOptions): PluginActionResult<{
     pluginKey: string;
@@ -381,6 +537,7 @@ declare function parseManifestObject(parsed: Record<string, unknown>, options?:
     connections: PluginConnectionRequirement[];
     entities: PluginEntityRequirement[];
     cervioApis: PluginCervioApiRequirement[];
+    settings: PluginSettingsFieldRequirement[];
 }>;
 /** Manifest JSON for hashing: drop author `version` so Cervio-owned labels do not affect dedup. */
 declare function manifestJsonForContentHash(raw: Record<string, unknown>): string;
@@ -421,4 +578,4 @@ declare function validatePluginZipBuffer(buffer: Buffer, options?: ParseManifest
     contentSha256: string;
 }>>;
 
-export { type AllowedApiRule, DEFAULT_PLUGIN_DECLARABLE_CAPABILITIES, EXTERNAL_CONNECTION_ALLOWED_HOSTS, EXTERNAL_CONNECTION_HTTP_METHODS, type ExternalConnectionHttpMethod, MAX_PLUGIN_UNCOMPRESSED_BYTES, MAX_PLUGIN_ZIP_BYTES, MAX_PLUGIN_ZIP_ENTRIES, OAUTH_PROVIDER_KEY_RE, PLUGIN_ARTIFACT_BUCKET, PLUGIN_KEY_RE, PLUGIN_VERSION_SELECT, type PackPluginResult, type ParseManifestOptions, type ParsedPluginManifest, type PluginActionResult, type PluginCervioApiRequirement, type PluginConnectionRequirement, type PluginEntityAccess, type PluginEntityRequirement, type PluginManifestZod, type PluginType, type PluginVersionRow, assertZipFile, assertZipSafe, compareSemverDesc, computePluginContentSha256, isExternalConnectionProvider, loadZipFromBuffer, manifestJsonForContentHash, nextPatchVersion, normalizeExactApiHost, normalizePluginKey, packPlugin, parseManifestObject, parsePluginCervioApiRequirements, parsePluginConnections, parsePluginEntityRequirements, parseZipManifest, pluginManifestZodSchema, sha256Hex, validatePluginDir, validatePluginZipBuffer };
+export { EXTERNAL_CONNECTION_ALLOWED_HOSTS, EXTERNAL_CONNECTION_HTTP_METHODS, OAUTH_PROVIDER_KEY_RE, type PackPluginResult, ParseManifestOptions, ParsedPluginManifest, PluginActionResult, PluginCervioApiRequirement, PluginConnectionRequirement, PluginEntityRequirement, type PluginManifestZod, PluginSettingsFieldRequirement, PluginType, type PolicyHookCaller, type PolicyHookEvent, type PolicyHookInput, type PolicyHookResult, type PolicyHost, assertPolicyEntrySelfContained, compareSemverDesc, computePluginContentSha256, findBareModuleSpecifiers, isExternalConnectionProvider, isPolicyPluginType, loadZipFromBuffer, manifestJsonForContentHash, nextPatchVersion, normalizeExactApiHost, normalizePluginKey, normalizeToPolicyPluginType, packPlugin, parseManifestObject, parsePluginCervioApiRequirements, parsePluginConnections, parsePluginEntityRequirements, parsePluginSettingsRequirements, parseZipManifest, pluginManifestZodSchema, sha256Hex, validatePluginDir, validatePluginZipBuffer };