@vonzio/plugin-api 0.1.0

package/index.js

@@ -0,0 +1,24 @@
+// Plugin contract for vonzio. A plugin is a self-contained npm package
+// that the loader in core-server imports at boot, parses config for,
+// applies migrations from, and calls init() on. From there the plugin
+// registers routes / notification handlers / MCP servers / background
+// jobs to integrate with the host runtime.
+//
+// This file is the SURFACE plugin authors program against. Keep it
+// minimal -- once shipped, breaking changes require a major bump and
+// a migration guide.
+/**
+ * Current plugin-api version. Plugins encode the version they were built
+ * against in their package.json `vonzio.apiVersion`; the loader rejects
+ * plugins whose major differs or whose minor is ahead of core's (see
+ * `assertApiCompatible`). Bumped to 1.0.0 with the external-loader contract
+ * (docs/PLUGIN_LOADER_SPEC.md) — the loader surface is now a stability
+ * commitment.
+ */
+export const PLUGIN_API_VERSION = "1.0.0";
+export { PLUGIN_CAPABILITIES, CAPABILITY_SURFACE_MAP, ROOT_EQUIVALENT_COMBINATIONS, BUILTIN_ONLY_CAPABILITIES, isPluginCapability, } from "./capabilities.js";
+export { MANIFEST_ALLOWED_KEYS, POLICY_ENTRY_ALLOWED_KEYS, SCHEMA_PREFIX_PATTERN, MTLS_SECRET_NAME_PATTERN, } from "./manifest.js";
+export { validateManifest, validatePolicy, matchOutboundHost, normalizeHostPattern, } from "./manifest-validate.js";
+export { CapabilityViolationError, OutboundHostViolationError, DbScopeViolationError, PluginRefusedError, PolicyViolationError, REFUSAL_REASONS, } from "./errors.js";
+export { assertApiCompatible } from "./version.js";
+//# sourceMappingURL=index.js.map

package/manifest-validate.d.ts

@@ -0,0 +1,44 @@
+import { type OperatorPolicy, type PluginManifest } from "./manifest.js";
+import { type RefusalReason } from "./errors.js";
+export type ManifestValidationResult = {
+    ok: true;
+    manifest: PluginManifest;
+} | {
+    ok: false;
+    reason: RefusalReason;
+    message: string;
+};
+/**
+ * Normalize + validate one `outboundHosts` manifest entry into its canonical
+ * comparison form: lowercased, trailing-dot-stripped, IDNA/punycode-encoded,
+ * with a single leading `*.` glob preserved. Throws on malformed entries.
+ *
+ * Rules (§3 "Outbound host matching"):
+ *  - hostnames only — `/ : ? # @` and whitespace rejected (schemes, ports,
+ *    paths, userinfo are not part of the match)
+ *  - one leading `*.` glob allowed (matches exactly one DNS label); `**`,
+ *    mid-pattern `*`, or a bare `*` are rejected
+ *  - IDNA: the non-glob remainder is ASCII-encoded via the URL parser
+ */
+export declare function normalizeHostPattern(entry: string): string;
+/**
+ * Does `hostname` (from `url.hostname` — already lowercased + IDNA) match any
+ * normalized pattern? Glob `*.x.com` matches exactly one extra leading label.
+ */
+export declare function matchOutboundHost(hostname: string, patterns: readonly string[]): boolean;
+/**
+ * Validate the `vonzio` block from a plugin's package.json. Returns a
+ * discriminated result so the loader can map the failure to the right §11
+ * refusal reason without this module importing the loader. Does NOT run the
+ * apiVersion compatibility check (that's assertApiCompatible) nor any I/O
+ * (backendEntry existence, hashing) — those are the loader's job.
+ */
+export declare function validateManifest(raw: unknown): ManifestValidationResult;
+/**
+ * Validate the operator policy file (or the shipped builtins policy). The
+ * policy file is operator-owned config: a malformed file is a hard error
+ * (throws PolicyViolationError) rather than a per-plugin skip. Strict:
+ * unknown per-entry keys are rejected (mirrors the manifest stance).
+ */
+export declare function validatePolicy(raw: unknown, sourceLabel?: string): OperatorPolicy;
+//# sourceMappingURL=manifest-validate.d.ts.map

package/manifest-validate.js

@@ -0,0 +1,338 @@
+// Pure, dependency-free validators for the plugin manifest (the package.json
+// `vonzio` block) and the operator policy file, plus the runtime outbound-host
+// matcher. No I/O — the loader reads files and calls these. Strict: unknown
+// fields are rejected so a typo (`capabilites`) can't leave a plugin ungated.
+// See docs/PLUGIN_LOADER_SPEC.md §3 ("Outbound host matching", "Policy file
+// JSON schema"), §4.
+import { isPluginCapability, } from "./capabilities.js";
+import { MANIFEST_ALLOWED_KEYS, MTLS_SECRET_NAME_PATTERN, POLICY_ENTRY_ALLOWED_KEYS, SCHEMA_PREFIX_PATTERN, } from "./manifest.js";
+import { PolicyViolationError } from "./errors.js";
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Characters that disqualify a string from being a bare hostname pattern. */
+const HOST_FORBIDDEN_CHARS = /[/:?#@\s]/;
+/**
+ * Normalize + validate one `outboundHosts` manifest entry into its canonical
+ * comparison form: lowercased, trailing-dot-stripped, IDNA/punycode-encoded,
+ * with a single leading `*.` glob preserved. Throws on malformed entries.
+ *
+ * Rules (§3 "Outbound host matching"):
+ *  - hostnames only — `/ : ? # @` and whitespace rejected (schemes, ports,
+ *    paths, userinfo are not part of the match)
+ *  - one leading `*.` glob allowed (matches exactly one DNS label); `**`,
+ *    mid-pattern `*`, or a bare `*` are rejected
+ *  - IDNA: the non-glob remainder is ASCII-encoded via the URL parser
+ */
+export function normalizeHostPattern(entry) {
+    if (typeof entry !== "string" || entry.length === 0) {
+        throw new Error("outboundHosts entry must be a non-empty string");
+    }
+    let host = entry.trim().toLowerCase().replace(/\.$/, "");
+    let glob = false;
+    if (host.startsWith("*.")) {
+        glob = true;
+        host = host.slice(2);
+    }
+    if (host.includes("*")) {
+        throw new Error(`Invalid outboundHosts entry "${entry}": "*" is only allowed as a single leading label (e.g. *.slack.com)`);
+    }
+    if (host.length === 0) {
+        throw new Error(`Invalid outboundHosts entry "${entry}": empty host after glob`);
+    }
+    if (HOST_FORBIDDEN_CHARS.test(host)) {
+        throw new Error(`Invalid outboundHosts entry "${entry}": hostnames only — no scheme, port, path, or userinfo`);
+    }
+    // IDNA-encode via the URL parser (applies punycode + validation). A host
+    // with an illegal character set will throw here.
+    let encoded;
+    try {
+        encoded = new URL(`http://${host}`).hostname;
+    }
+    catch {
+        throw new Error(`Invalid outboundHosts entry "${entry}": not a valid hostname`);
+    }
+    return glob ? `*.${encoded}` : encoded;
+}
+/**
+ * Does `hostname` (from `url.hostname` — already lowercased + IDNA) match any
+ * normalized pattern? Glob `*.x.com` matches exactly one extra leading label.
+ */
+export function matchOutboundHost(hostname, patterns) {
+    const host = hostname.trim().toLowerCase().replace(/\.$/, "");
+    for (const raw of patterns) {
+        // Patterns are expected pre-normalized (validateManifest stores them so),
+        // but normalize defensively in case a caller passes raw manifest strings.
+        let pattern;
+        try {
+            pattern = raw.startsWith("*.") || !HOST_FORBIDDEN_CHARS.test(raw)
+                ? normalizeHostPattern(raw)
+                : raw.toLowerCase().replace(/\.$/, "");
+        }
+        catch {
+            continue; // a malformed pattern never matches
+        }
+        if (pattern.startsWith("*.")) {
+            const suffix = pattern.slice(2);
+            const labels = host.split(".");
+            const suffixLabels = suffix.split(".");
+            if (labels.length === suffixLabels.length + 1 &&
+                labels.slice(1).join(".") === suffix) {
+                return true;
+            }
+        }
+        else if (host === pattern) {
+            return true;
+        }
+    }
+    return false;
+}
+function validateRoutePrefix(raw) {
+    if (!isPlainObject(raw))
+        return { error: "routePrefix must be an object" };
+    if (raw.kind === "auto") {
+        if (Object.keys(raw).length !== 1)
+            return { error: 'routePrefix {kind:"auto"} takes no other fields' };
+        return { kind: "auto" };
+    }
+    if (raw.kind === "absolute") {
+        const extra = Object.keys(raw).filter((k) => k !== "kind" && k !== "prefix");
+        if (extra.length)
+            return { error: `routePrefix has unknown fields: ${extra.join(", ")}` };
+        const p = raw.prefix;
+        const arr = Array.isArray(p) ? p : [p];
+        if (arr.length === 0)
+            return { error: "routePrefix.absolute.prefix is empty" };
+        for (const one of arr) {
+            if (typeof one !== "string" || !one.startsWith("/")) {
+                return { error: `routePrefix.absolute.prefix entries must be absolute paths: ${String(one)}` };
+            }
+        }
+        return { kind: "absolute", prefix: p };
+    }
+    return { error: `routePrefix.kind must be "auto" or "absolute", got ${JSON.stringify(raw.kind)}` };
+}
+/**
+ * Validate the `vonzio` block from a plugin's package.json. Returns a
+ * discriminated result so the loader can map the failure to the right §11
+ * refusal reason without this module importing the loader. Does NOT run the
+ * apiVersion compatibility check (that's assertApiCompatible) nor any I/O
+ * (backendEntry existence, hashing) — those are the loader's job.
+ */
+export function validateManifest(raw) {
+    const fail = (message, reason = "manifest_invalid") => ({ ok: false, reason, message });
+    if (!isPlainObject(raw))
+        return fail("vonzio manifest block is missing or not an object");
+    // Strict: reject unknown keys (typo guard).
+    const unknown = Object.keys(raw).filter((k) => !MANIFEST_ALLOWED_KEYS.has(k));
+    if (unknown.length)
+        return fail(`manifest has unknown fields: ${unknown.join(", ")}`);
+    if (typeof raw.apiVersion !== "string" || raw.apiVersion.length === 0) {
+        return fail("manifest.apiVersion must be a non-empty string");
+    }
+    if (typeof raw.backendEntry !== "string" || raw.backendEntry.length === 0) {
+        return fail("manifest.backendEntry must be a non-empty string");
+    }
+    if (raw.frontendEntry !== undefined && typeof raw.frontendEntry !== "string") {
+        return fail("manifest.frontendEntry must be a string when present");
+    }
+    if (!Array.isArray(raw.capabilities)) {
+        return fail("manifest.capabilities must be an array");
+    }
+    const capabilities = [];
+    for (const c of raw.capabilities) {
+        if (typeof c !== "string" || !isPluginCapability(c)) {
+            return fail(`manifest.capabilities contains an unknown capability: ${JSON.stringify(c)}`);
+        }
+        capabilities.push(c);
+    }
+    const declaresHttp = capabilities.includes("http.outbound");
+    const declaresDb = capabilities.includes("db.scoped") || capabilities.includes("db.access");
+    // outboundHosts: required + non-empty iff http.outbound; normalized.
+    let outboundHosts;
+    if (raw.outboundHosts !== undefined) {
+        if (!Array.isArray(raw.outboundHosts))
+            return fail("manifest.outboundHosts must be an array");
+        try {
+            outboundHosts = raw.outboundHosts.map((h) => normalizeHostPattern(h));
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : String(err));
+        }
+    }
+    if (declaresHttp && (!outboundHosts || outboundHosts.length === 0)) {
+        return fail("manifest declares http.outbound but outboundHosts is missing or empty");
+    }
+    if (!declaresHttp && outboundHosts && outboundHosts.length > 0) {
+        return fail("manifest.outboundHosts is set but http.outbound capability is not declared");
+    }
+    // schemaPrefix: required iff db.* and must be a DB-safe identifier.
+    let schemaPrefix;
+    if (raw.schemaPrefix !== undefined) {
+        if (typeof raw.schemaPrefix !== "string")
+            return fail("manifest.schemaPrefix must be a string");
+        if (!SCHEMA_PREFIX_PATTERN.test(raw.schemaPrefix)) {
+            return fail(`manifest.schemaPrefix "${raw.schemaPrefix}" must match ${SCHEMA_PREFIX_PATTERN}`, "schema_prefix_invalid");
+        }
+        schemaPrefix = raw.schemaPrefix;
+    }
+    if (declaresDb && !schemaPrefix) {
+        return fail("manifest declares db.scoped/db.access but schemaPrefix is missing", "schema_prefix_invalid");
+    }
+    // mtlsSecrets: required + non-empty iff secrets.mtls; names pattern-checked.
+    const declaresMtls = capabilities.includes("secrets.mtls");
+    let mtlsSecrets;
+    if (raw.mtlsSecrets !== undefined) {
+        if (!Array.isArray(raw.mtlsSecrets))
+            return fail("manifest.mtlsSecrets must be an array");
+        const names = [];
+        for (const n of raw.mtlsSecrets) {
+            if (typeof n !== "string" || !MTLS_SECRET_NAME_PATTERN.test(n)) {
+                return fail(`manifest.mtlsSecrets entry ${JSON.stringify(n)} must match ${MTLS_SECRET_NAME_PATTERN}`);
+            }
+            names.push(n);
+        }
+        if (new Set(names).size !== names.length)
+            return fail("manifest.mtlsSecrets has duplicate names");
+        mtlsSecrets = names;
+    }
+    if (declaresMtls && (!mtlsSecrets || mtlsSecrets.length === 0)) {
+        return fail("manifest declares secrets.mtls but mtlsSecrets is missing or empty");
+    }
+    if (!declaresMtls && mtlsSecrets && mtlsSecrets.length > 0) {
+        return fail("manifest.mtlsSecrets is set but secrets.mtls capability is not declared");
+    }
+    // routePrefix (optional; default auto).
+    let routePrefix;
+    if (raw.routePrefix !== undefined) {
+        const rp = validateRoutePrefix(raw.routePrefix);
+        if ("error" in rp)
+            return fail(`manifest.${rp.error}`);
+        routePrefix = rp;
+    }
+    return {
+        ok: true,
+        manifest: {
+            apiVersion: raw.apiVersion,
+            backendEntry: raw.backendEntry,
+            ...(raw.frontendEntry !== undefined ? { frontendEntry: raw.frontendEntry } : {}),
+            capabilities,
+            ...(outboundHosts !== undefined ? { outboundHosts } : {}),
+            ...(schemaPrefix !== undefined ? { schemaPrefix } : {}),
+            ...(mtlsSecrets !== undefined ? { mtlsSecrets } : {}),
+            ...(routePrefix !== undefined ? { routePrefix } : {}),
+        },
+    };
+}
+/**
+ * Validate the operator policy file (or the shipped builtins policy). The
+ * policy file is operator-owned config: a malformed file is a hard error
+ * (throws PolicyViolationError) rather than a per-plugin skip. Strict:
+ * unknown per-entry keys are rejected (mirrors the manifest stance).
+ */
+export function validatePolicy(raw, sourceLabel = "policy") {
+    if (!isPlainObject(raw)) {
+        throw new PolicyViolationError(`${sourceLabel}: file is not a JSON object`);
+    }
+    if (raw.policy_version !== "1") {
+        throw new PolicyViolationError(`${sourceLabel}: policy_version must be "1", got ${JSON.stringify(raw.policy_version)}`);
+    }
+    const topUnknown = Object.keys(raw).filter((k) => k !== "policy_version" && k !== "plugins");
+    if (topUnknown.length) {
+        throw new PolicyViolationError(`${sourceLabel}: unknown top-level fields: ${topUnknown.join(", ")}`);
+    }
+    if (!isPlainObject(raw.plugins)) {
+        throw new PolicyViolationError(`${sourceLabel}: "plugins" must be an object keyed by package name`);
+    }
+    const plugins = {};
+    for (const [name, entryRaw] of Object.entries(raw.plugins)) {
+        plugins[name] = validatePolicyEntry(name, entryRaw, sourceLabel);
+    }
+    return { policy_version: "1", plugins };
+}
+function validatePolicyEntry(name, raw, sourceLabel) {
+    const bad = (msg) => {
+        throw new PolicyViolationError(`${sourceLabel}: plugin "${name}": ${msg}`);
+    };
+    if (!isPlainObject(raw))
+        return bad("entry is not an object");
+    const unknown = Object.keys(raw).filter((k) => !POLICY_ENTRY_ALLOWED_KEYS.has(k));
+    if (unknown.length)
+        bad(`unknown fields: ${unknown.join(", ")}`);
+    if (typeof raw.version !== "string" || !raw.version)
+        bad("version must be a non-empty string");
+    if (typeof raw.approved_hash_sha256 !== "string" || !raw.approved_hash_sha256) {
+        bad("approved_hash_sha256 must be a non-empty string");
+    }
+    if (!Array.isArray(raw.approved_capabilities))
+        bad("approved_capabilities must be an array");
+    const caps = [];
+    for (const c of raw.approved_capabilities) {
+        if (typeof c !== "string" || !isPluginCapability(c))
+            bad(`approved_capabilities has unknown capability ${JSON.stringify(c)}`);
+        caps.push(c);
+    }
+    if (!Array.isArray(raw.approved_outbound_hosts))
+        bad("approved_outbound_hosts must be an array");
+    const hosts = [];
+    for (const h of raw.approved_outbound_hosts) {
+        if (typeof h !== "string")
+            bad("approved_outbound_hosts entries must be strings");
+        hosts.push(normalizeHostPattern(h));
+    }
+    if (raw.approved_frontend !== undefined && typeof raw.approved_frontend !== "boolean") {
+        bad("approved_frontend must be a boolean when present");
+    }
+    for (const optStr of ["approved_at", "approved_by", "approval_reason"]) {
+        if (raw[optStr] !== undefined && typeof raw[optStr] !== "string")
+            bad(`${optStr} must be a string when present`);
+    }
+    // mtls_secrets: optional map of logical name -> { cert, key, passphraseEnv? }
+    // host file paths. Validated strictly so a malformed mapping fails the whole
+    // policy file rather than silently dropping a cert at runtime.
+    let mtlsSecrets;
+    if (raw.mtls_secrets !== undefined) {
+        if (!isPlainObject(raw.mtls_secrets))
+            bad("mtls_secrets must be an object keyed by logical name");
+        const out = {};
+        for (const [secretName, filesRaw] of Object.entries(raw.mtls_secrets)) {
+            if (!MTLS_SECRET_NAME_PATTERN.test(secretName))
+                bad(`mtls_secrets name "${secretName}" must match ${MTLS_SECRET_NAME_PATTERN}`);
+            if (!isPlainObject(filesRaw))
+                bad(`mtls_secrets["${secretName}"] must be an object`);
+            const files = filesRaw;
+            const fileUnknown = Object.keys(files).filter((k) => k !== "cert" && k !== "key" && k !== "ca" && k !== "passphraseEnv");
+            if (fileUnknown.length)
+                bad(`mtls_secrets["${secretName}"] has unknown fields: ${fileUnknown.join(", ")}`);
+            if (typeof files.cert !== "string" || !files.cert)
+                bad(`mtls_secrets["${secretName}"].cert must be a non-empty path string`);
+            if (typeof files.key !== "string" || !files.key)
+                bad(`mtls_secrets["${secretName}"].key must be a non-empty path string`);
+            if (files.ca !== undefined && (typeof files.ca !== "string" || !files.ca)) {
+                bad(`mtls_secrets["${secretName}"].ca must be a non-empty path string when present`);
+            }
+            if (files.passphraseEnv !== undefined && (typeof files.passphraseEnv !== "string" || !files.passphraseEnv)) {
+                bad(`mtls_secrets["${secretName}"].passphraseEnv must be a non-empty string when present`);
+            }
+            out[secretName] = {
+                cert: files.cert,
+                key: files.key,
+                ...(files.ca !== undefined ? { ca: files.ca } : {}),
+                ...(files.passphraseEnv !== undefined ? { passphraseEnv: files.passphraseEnv } : {}),
+            };
+        }
+        mtlsSecrets = out;
+    }
+    return {
+        version: raw.version,
+        approved_hash_sha256: raw.approved_hash_sha256,
+        approved_capabilities: caps,
+        approved_outbound_hosts: hosts,
+        ...(raw.approved_frontend !== undefined ? { approved_frontend: raw.approved_frontend } : {}),
+        ...(mtlsSecrets !== undefined ? { mtls_secrets: mtlsSecrets } : {}),
+        ...(raw.approved_at !== undefined ? { approved_at: raw.approved_at } : {}),
+        ...(raw.approved_by !== undefined ? { approved_by: raw.approved_by } : {}),
+        ...(raw.approval_reason !== undefined ? { approval_reason: raw.approval_reason } : {}),
+    };
+}
+//# sourceMappingURL=manifest-validate.js.map

package/manifest.d.ts

@@ -0,0 +1,121 @@
+import type { PluginCapability } from "./capabilities.js";
+/**
+ * Where the plugin's routes live in the URL space.
+ *  - `auto` (default): mount under a real Fastify child scope at
+ *    `/plugins/<name>`.
+ *  - `absolute`: legacy escape hatch for externally-registered URLs (Slack
+ *    OAuth callback, Telegram webhook). v1 registers the child with NO scope
+ *    prefix — the plugin uses full paths as before — and the prefix string is
+ *    deny-list-checked + audit-logged. `prefix` may be a single string or an
+ *    array for plugins spanning multiple legacy roots (Slack/Telegram each
+ *    own `/v1/integrations/<name>` AND `/api/<name>`).
+ */
+export type ManifestRoutePrefix = {
+    kind: "auto";
+} | {
+    kind: "absolute";
+    prefix: string | string[];
+};
+/**
+ * The `vonzio` block in a plugin package's package.json. Strictly validated
+ * (unknown fields rejected) by validateManifest in manifest-validate.ts.
+ */
+export interface PluginManifest {
+    /**
+     * plugin-api semver this plugin targets. Loader refuses unless
+     * `plugin.major === core.major && plugin.minor <= core.minor`.
+     */
+    apiVersion: string;
+    /** Path to the backend bundle, relative to package root. Must be a real
+     *  file inside (a child of) the package root after realpath. */
+    backendEntry: string;
+    /** Path to the frontend bundle. Built-ins: unconditional. Externals: only
+     *  when the operator policy sets `approved_frontend: true`. (Frontend
+     *  bundling itself is PR 3J.2; the manifest field + gate ship here.) */
+    frontendEntry?: string;
+    /** Declared capabilities. Each must be a known PluginCapability. */
+    capabilities: PluginCapability[];
+    /** Required + non-empty iff `http.outbound` is declared. Hostname patterns
+     *  only — schemes/ports/paths/userinfo rejected; single-label `*` glob. */
+    outboundHosts?: string[];
+    /** Required iff `db.scoped` or `db.access` is declared. DB-safe identifier
+     *  matching ^[a-z][a-z0-9_]{1,30}$. */
+    schemaPrefix?: string;
+    /** Logical mTLS client-cert names the plugin needs (e.g. ["teller-client"]).
+     *  Required + non-empty iff `secrets.mtls` is declared. Each must match
+     *  {@link MTLS_SECRET_NAME_PATTERN}; the operator maps each to host file paths
+     *  via `PolicyEntry.mtls_secrets`. The plugin resolves them with
+     *  `ctx.secrets.mtls(name)`. See §5, §10. */
+    mtlsSecrets?: string[];
+    /** Route mounting strategy. Defaults to `{ kind: "auto" }` when absent. */
+    routePrefix?: ManifestRoutePrefix;
+}
+/**
+ * Operator-provisioned file paths backing one logical mTLS secret name. The
+ * paths point at PEM files on the host (mounted via Docker/k8s secret volumes);
+ * core reads them server-side and never exposes the bytes to the plugin.
+ */
+export interface MtlsSecretFiles {
+    /** Path to the PEM client certificate file on the host. */
+    cert: string;
+    /** Path to the PEM private-key file on the host. */
+    key: string;
+    /** Optional path to a PEM CA bundle to trust the SERVER's certificate. Omit
+     *  for endpoints with a publicly-trusted cert (e.g. api.teller.io); set it
+     *  for private mTLS endpoints that present a private server CA. */
+    ca?: string;
+    /** Optional env var NAME holding the key passphrase (never the passphrase
+     *  itself — the policy file may be committed). */
+    passphraseEnv?: string;
+}
+/** Source of a loaded plugin. Drives the external-only validation rules. */
+export type PluginSource = "builtin" | "external";
+/**
+ * One operator-policy entry — the operator's GRANT against a plugin's
+ * manifest REQUEST. Strictly validated (unknown fields rejected) by
+ * validatePolicy. See §4.
+ */
+export interface PolicyEntry {
+    /** Plugin version the operator approved. Compared to the installed
+     *  package version (unless TRACK_VERSIONS=loose). */
+    version: string;
+    /** SHA-256 of the package directory (excl. node_modules) at approval. */
+    approved_hash_sha256: string;
+    /** Manifest.capabilities must be a subset of this. */
+    approved_capabilities: PluginCapability[];
+    /** Manifest.outboundHosts must be a subset of this. May be empty. */
+    approved_outbound_hosts: string[];
+    /** Operator grant for the plugin's frontend to be bundled into the
+     *  dashboard. Default false when absent. */
+    approved_frontend?: boolean;
+    /** Maps each `manifest.mtlsSecrets` name the operator provisioned to its host
+     *  PEM file paths. Every name the manifest declares must appear here, else the
+     *  loader refuses (policy_mtls_secret_drift). */
+    mtls_secrets?: Record<string, MtlsSecretFiles>;
+    /** ISO-8601 approval timestamp. */
+    approved_at?: string;
+    /** Operator identity (e.g. email). */
+    approved_by?: string;
+    /** Free-form rationale (from `--reason`); required for dangerous combos. */
+    approval_reason?: string;
+}
+/**
+ * The operator policy file (`vonzio-plugins.json`) and the shipped builtins
+ * policy (`vonzio-plugins.builtins.json`) share this shape.
+ */
+export interface OperatorPolicy {
+    /** Pinned to "1" for v1. */
+    policy_version: string;
+    /** Keyed by package name. */
+    plugins: Record<string, PolicyEntry>;
+}
+/** Keys allowed in the manifest `vonzio` block — used by the strict
+ *  validator to reject typos / smuggled fields. */
+export declare const MANIFEST_ALLOWED_KEYS: ReadonlySet<string>;
+/** Keys allowed in one operator-policy entry. */
+export declare const POLICY_ENTRY_ALLOWED_KEYS: ReadonlySet<string>;
+/** DB-safe schema-prefix identifier pattern (§3 step 14). */
+export declare const SCHEMA_PREFIX_PATTERN: RegExp;
+/** Logical mTLS secret name pattern: lowercase, digits, hyphens; ≤63 chars. */
+export declare const MTLS_SECRET_NAME_PATTERN: RegExp;
+//# sourceMappingURL=manifest.d.ts.map

package/manifest.js

@@ -0,0 +1,37 @@
+// Static plugin manifest (the `vonzio` block in a plugin's package.json) and
+// the operator policy file shapes. The loader reads + validates the manifest
+// from disk BEFORE importing the plugin's entry point, and cross-checks it
+// against the operator policy. See docs/PLUGIN_LOADER_SPEC.md §3, §4.
+//
+// These are the DECLARED shapes (plugin-author request + operator grant).
+// The runtime `VonzioPlugin` default export (name, init, configSchema,
+// migrations) is a separate object validated after import — see index.ts.
+/** Keys allowed in the manifest `vonzio` block — used by the strict
+ *  validator to reject typos / smuggled fields. */
+export const MANIFEST_ALLOWED_KEYS = new Set([
+    "apiVersion",
+    "backendEntry",
+    "frontendEntry",
+    "capabilities",
+    "outboundHosts",
+    "schemaPrefix",
+    "mtlsSecrets",
+    "routePrefix",
+]);
+/** Keys allowed in one operator-policy entry. */
+export const POLICY_ENTRY_ALLOWED_KEYS = new Set([
+    "version",
+    "approved_hash_sha256",
+    "approved_capabilities",
+    "approved_outbound_hosts",
+    "approved_frontend",
+    "mtls_secrets",
+    "approved_at",
+    "approved_by",
+    "approval_reason",
+]);
+/** DB-safe schema-prefix identifier pattern (§3 step 14). */
+export const SCHEMA_PREFIX_PATTERN = /^[a-z][a-z0-9_]{1,30}$/;
+/** Logical mTLS secret name pattern: lowercase, digits, hyphens; ≤63 chars. */
+export const MTLS_SECRET_NAME_PATTERN = /^[a-z][a-z0-9-]{0,62}$/;
+//# sourceMappingURL=manifest.js.map

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@vonzio/plugin-api",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Plugin contract for vonzio. Defines the types + helpers a plugin author implements; defines what core-server's loader and bus implement. Stable surface: breaking changes require a major bump.",
+  "license": "AGPL-3.0-or-later",
+  "homepage": "https://vonzio.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vonzio/vonzio.git",
+    "directory": "packages/plugin-api"
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./frontend": {
+      "types": "./frontend.d.ts",
+      "import": "./frontend.js"
+    },
+    "./policy": {
+      "types": "./policy.d.ts",
+      "import": "./policy.js"
+    }
+  },
+  "dependencies": {
+    "@vonzio/shared": "^0.1.0"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0",
+    "react": "^19.0.0",
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "files": [
+    "**/*.js",
+    "**/*.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}