@cervio/plugin-core 0.1.1 → 1.0.0

package/dist/index.d.ts

@@ -1,114 +1,5 @@
-import JSZip from 'jszip';
-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 | null;
-    artifact_entry_path?: string | null;
-    artifact_sha256: string | null;
-    content_sha256?: string | null;
-    artifact_size_bytes: number | null;
-    created_at: string;
-    /** Soft-delete timestamp; when set the row is history-only (strikethrough in Admin). */
-    deleted_at?: string | null;
-    deleted_by?: string | null;
-}
-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, deleted_at, deleted_by";
-/**
- * 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"];
-
-/** 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[];
-
-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;
-/** Lightweight host check (no DNS); mirrors host `normalizeExactApiHost` shape rules. */
-declare function normalizeExactApiHost(raw: string): string | null;
-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>;
+import { P as ParseManifestOptions, a as PluginActionResult, b as PluginType, c as PluginConnectionRequirement, d as PluginEntityRequirement, e as PluginCervioApiRequirement, f as PluginSettingsFieldRequirement, g as PluginBootRequest, h as ParsedPluginManifest, i as PluginZip } from './browser-Ddj__JFI.js';
+export { A as AllowedApiRule, D as DEFAULT_PLUGIN_DECLARABLE_CAPABILITIES, E as ExternalConnectionHttpMethod, M as MAX_PLUGIN_UNCOMPRESSED_BYTES, j as MAX_PLUGIN_ZIP_BYTES, k as MAX_PLUGIN_ZIP_ENTRIES, l as PLUGIN_ARTIFACT_SOFT_STRONG_WARN_BYTES, m as PLUGIN_ARTIFACT_SOFT_WARN_BYTES, n as PLUGIN_KEY_RE, o as PluginEntityAccess, p as PluginSettingsFieldOption, q as PluginSettingsFieldType, r as assertZipFile, s as isDeclarableCervioApiRequirement, t as isDeclaredCervioApiRequest, u as parsePluginBootRequests, v as parsePluginCervioApiRequirements, w as parsePluginEntityRequirements, x as readPluginZip } from './browser-Ddj__JFI.js';
 
 /**
  * Next patch version assigned by Cervio. Ignores pre-release/build metadata on
@@ -118,261 +9,62 @@ declare function nextPatchVersion(latest: string | null | undefined): string;
 /** Compare core x.y.z numerically (descending sort helper). */
 declare function compareSemverDesc(a: string, b: string): number;
 
-/** Zod schema documenting the author-facing manifest shape (source of truth for JSON Schema). */
-declare const pluginManifestZodSchema: z.ZodObject<{
-    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"]>>;
-    kind: z.ZodOptional<z.ZodString>;
-    version: z.ZodOptional<z.ZodString>;
-    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<{
-        id: z.ZodString;
-        provider: z.ZodString;
-        scopes: z.ZodArray<z.ZodString, "many">;
-        allowed_apis: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            host: z.ZodString;
-            methods: z.ZodArray<z.ZodString, "many">;
-            path_prefix: z.ZodOptional<z.ZodString>;
-            pathPrefix: z.ZodOptional<z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            host: string;
-            methods: string[];
-            path_prefix?: string | undefined;
-            pathPrefix?: string | undefined;
-        }, {
-            host: string;
-            methods: string[];
-            path_prefix?: string | undefined;
-            pathPrefix?: string | undefined;
-        }>, "many">>;
-        allowedApis: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
-    }, "strip", z.ZodTypeAny, {
-        id: string;
-        provider: string;
-        scopes: string[];
-        allowed_apis?: {
-            host: string;
-            methods: string[];
-            path_prefix?: string | undefined;
-            pathPrefix?: string | undefined;
-        }[] | undefined;
-        allowedApis?: unknown[] | undefined;
-    }, {
-        id: string;
-        provider: string;
-        scopes: string[];
-        allowed_apis?: {
-            host: string;
-            methods: string[];
-            path_prefix?: string | undefined;
-            pathPrefix?: string | undefined;
-        }[] | undefined;
-        allowedApis?: unknown[] | undefined;
-    }>, "many">>;
-    entities: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        forms: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        access: z.ZodOptional<z.ZodArray<z.ZodEnum<["read", "write"]>, "many">>;
-    }, "strip", z.ZodTypeAny, {
-        name: string;
-        fields?: string[] | undefined;
-        forms?: string[] | undefined;
-        access?: ("read" | "write")[] | undefined;
-    }, {
-        name: string;
-        fields?: string[] | undefined;
-        forms?: string[] | undefined;
-        access?: ("read" | "write")[] | undefined;
-    }>, "many">>;
-    cervio_apis: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        method: z.ZodOptional<z.ZodString>;
-        path_prefix: z.ZodOptional<z.ZodString>;
-        pathPrefix: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        method?: string | undefined;
-        path_prefix?: string | undefined;
-        pathPrefix?: string | undefined;
-    }, {
-        method?: string | undefined;
-        path_prefix?: string | undefined;
-        pathPrefix?: string | undefined;
-    }>, "many">>;
-    cervioApis: z.ZodOptional<z.ZodArray<z.ZodUnknown, "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"]>>;
-    kind: z.ZodOptional<z.ZodString>;
-    version: z.ZodOptional<z.ZodString>;
-    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<{
-        id: z.ZodString;
-        provider: z.ZodString;
-        scopes: z.ZodArray<z.ZodString, "many">;
-        allowed_apis: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            host: z.ZodString;
-            methods: z.ZodArray<z.ZodString, "many">;
-            path_prefix: z.ZodOptional<z.ZodString>;
-            pathPrefix: z.ZodOptional<z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            host: string;
-            methods: string[];
-            path_prefix?: string | undefined;
-            pathPrefix?: string | undefined;
-        }, {
-            host: string;
-            methods: string[];
-            path_prefix?: string | undefined;
-            pathPrefix?: string | undefined;
-        }>, "many">>;
-        allowedApis: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
-    }, "strip", z.ZodTypeAny, {
-        id: string;
-        provider: string;
-        scopes: string[];
-        allowed_apis?: {
-            host: string;
-            methods: string[];
-            path_prefix?: string | undefined;
-            pathPrefix?: string | undefined;
-        }[] | undefined;
-        allowedApis?: unknown[] | undefined;
-    }, {
-        id: string;
-        provider: string;
-        scopes: string[];
-        allowed_apis?: {
-            host: string;
-            methods: string[];
-            path_prefix?: string | undefined;
-            pathPrefix?: string | undefined;
-        }[] | undefined;
-        allowedApis?: unknown[] | undefined;
-    }>, "many">>;
-    entities: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        forms: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        access: z.ZodOptional<z.ZodArray<z.ZodEnum<["read", "write"]>, "many">>;
-    }, "strip", z.ZodTypeAny, {
-        name: string;
-        fields?: string[] | undefined;
-        forms?: string[] | undefined;
-        access?: ("read" | "write")[] | undefined;
-    }, {
-        name: string;
-        fields?: string[] | undefined;
-        forms?: string[] | undefined;
-        access?: ("read" | "write")[] | undefined;
-    }>, "many">>;
-    cervio_apis: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        method: z.ZodOptional<z.ZodString>;
-        path_prefix: z.ZodOptional<z.ZodString>;
-        pathPrefix: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        method?: string | undefined;
-        path_prefix?: string | undefined;
-        pathPrefix?: string | undefined;
-    }, {
-        method?: string | undefined;
-        path_prefix?: string | undefined;
-        pathPrefix?: string | undefined;
-    }>, "many">>;
-    cervioApis: z.ZodOptional<z.ZodArray<z.ZodUnknown, "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"]>>;
-    kind: z.ZodOptional<z.ZodString>;
-    version: z.ZodOptional<z.ZodString>;
-    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<{
-        id: z.ZodString;
-        provider: z.ZodString;
-        scopes: z.ZodArray<z.ZodString, "many">;
-        allowed_apis: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            host: z.ZodString;
-            methods: z.ZodArray<z.ZodString, "many">;
-            path_prefix: z.ZodOptional<z.ZodString>;
-            pathPrefix: z.ZodOptional<z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            host: string;
-            methods: string[];
-            path_prefix?: string | undefined;
-            pathPrefix?: string | undefined;
-        }, {
-            host: string;
-            methods: string[];
-            path_prefix?: string | undefined;
-            pathPrefix?: string | undefined;
-        }>, "many">>;
-        allowedApis: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
-    }, "strip", z.ZodTypeAny, {
+/**
+ * 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;
-        provider: string;
-        scopes: string[];
-        allowed_apis?: {
-            host: string;
-            methods: string[];
-            path_prefix?: string | undefined;
-            pathPrefix?: string | undefined;
-        }[] | undefined;
-        allowedApis?: unknown[] | undefined;
-    }, {
+        data: Record<string, unknown>;
+    } | null>;
+    listRecords(entityName: string, opts?: {
+        filters?: Record<string, unknown>;
+        limit?: number;
+        offset?: number;
+    }): Promise<Array<{
         id: string;
-        provider: string;
-        scopes: string[];
-        allowed_apis?: {
-            host: string;
-            methods: string[];
-            path_prefix?: string | undefined;
-            pathPrefix?: string | undefined;
-        }[] | undefined;
-        allowedApis?: unknown[] | undefined;
-    }>, "many">>;
-    entities: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        forms: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        access: z.ZodOptional<z.ZodArray<z.ZodEnum<["read", "write"]>, "many">>;
-    }, "strip", z.ZodTypeAny, {
-        name: string;
-        fields?: string[] | undefined;
-        forms?: string[] | undefined;
-        access?: ("read" | "write")[] | undefined;
-    }, {
-        name: string;
-        fields?: string[] | undefined;
-        forms?: string[] | undefined;
-        access?: ("read" | "write")[] | undefined;
-    }>, "many">>;
-    cervio_apis: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        method: z.ZodOptional<z.ZodString>;
-        path_prefix: z.ZodOptional<z.ZodString>;
-        pathPrefix: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        method?: string | undefined;
-        path_prefix?: string | undefined;
-        pathPrefix?: string | undefined;
-    }, {
-        method?: string | undefined;
-        path_prefix?: string | undefined;
-        pathPrefix?: string | undefined;
-    }>, "many">>;
-    cervioApis: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
-}, z.ZodTypeAny, "passthrough">>;
-type PluginManifestZod = z.infer<typeof pluginManifestZodSchema>;
+        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 normalizePluginKey(raw: string): string;
 declare function parseManifestObject(parsed: Record<string, unknown>, options?: ParseManifestOptions): PluginActionResult<{
@@ -384,11 +76,13 @@ declare function parseManifestObject(parsed: Record<string, unknown>, options?:
     connections: PluginConnectionRequirement[];
     entities: PluginEntityRequirement[];
     cervioApis: PluginCervioApiRequirement[];
+    settings: PluginSettingsFieldRequirement[];
+    bootRequests: PluginBootRequest[];
 }>;
 /** Manifest JSON for hashing: drop author `version` so Cervio-owned labels do not affect dedup. */
 declare function manifestJsonForContentHash(raw: Record<string, unknown>): string;
-declare function loadZipFromBuffer(buffer: ArrayBuffer | Buffer): Promise<PluginActionResult<JSZip>>;
-declare function parseZipManifest(file: File | Blob, options?: ParseManifestOptions): Promise<PluginActionResult<ParsedPluginManifest>>;
+/** Reads and validates the manifest of a plugin ZIP (an uploaded file, or its bytes). */
+declare function parseZipManifest(file: Blob | ArrayBuffer | Uint8Array, options?: ParseManifestOptions): Promise<PluginActionResult<ParsedPluginManifest>>;
 
 /**
  * Deterministic SHA-256 over:
@@ -397,7 +91,7 @@ declare function parseZipManifest(file: File | Blob, options?: ParseManifestOpti
  *
  * README / other root files and ZIP compression metadata do not affect the hash.
  */
-declare function computePluginContentSha256(zip: JSZip, rawManifest: Record<string, unknown>): Promise<PluginActionResult<string>>;
+declare function computePluginContentSha256(zip: PluginZip, rawManifest: Record<string, unknown>): PluginActionResult<string>;
 declare function sha256Hex(buffer: Buffer | Uint8Array): string;
 
 type PackPluginResult = {
@@ -424,4 +118,5 @@ 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 { ParseManifestOptions, ParsedPluginManifest, PluginActionResult, PluginBootRequest, PluginCervioApiRequirement, PluginConnectionRequirement, PluginEntityRequirement, PluginSettingsFieldRequirement, PluginType, PluginZip, compareSemverDesc, computePluginContentSha256, isPolicyPluginType, manifestJsonForContentHash, nextPatchVersion, normalizePluginKey, normalizeToPolicyPluginType, packPlugin, parseManifestObject, parseZipManifest, sha256Hex, validatePluginDir, validatePluginZipBuffer };
+export type { PackPluginResult, PolicyHookCaller, PolicyHookEvent, PolicyHookInput, PolicyHookResult, PolicyHost };