@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/extensions/org-config.js

@@ -0,0 +1,520 @@
+import { EXTENSION_POINTS, parseExtensionPoint, } from "@capybara-hq/plugin-sdk";
+import { assertItemInstallable, assertPluginSourcesInstallable, disabledPluginItems, pluginItemDisabled, } from "../catalog/requests.service.js";
+import { changedPaths, configFields, getPath, secretValues } from "../config/fields.js";
+import { createSecrets } from "../ctx/secrets.js";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { lockOrgAndAuthorize } from "../orgs/org-lock.js";
+import { configToJsonSchema } from "./config-json-schema.js";
+import { enabledExtensionsQuery, requiredExtensions } from "./enabled.js";
+import { permissionGroups } from "./permission-view.js";
+/** 内核自己的 secrets 命名空间（plugin-sdk 把 `kernel` 列为保留插件名，插件不会与之相撞）。 */
+const SECRETS_NAMESPACE = "kernel";
+const secretKey = (plugin, path) => `plugin-config:${plugin}:${path}`;
+/** 清单不可变：每个组织级 schema 的 JSON Schema 转换结果按 schema 对象缓存（只读、无跨请求状态）。 */
+const jsonSchemaCache = new WeakMap();
+function orgJsonSchema(schema) {
+    let js = jsonSchemaCache.get(schema);
+    if (!js) {
+        js = configToJsonSchema(schema);
+        jsonSchemaCache.set(schema, js);
+    }
+    return structuredClone(js);
+}
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** 按点路径设值，缺失的中间对象自动创建；中间节点不是对象时放弃（交给 schema 校验报错）。 */
+function setDeep(obj, path, value) {
+    const segs = path.split(".");
+    let node = obj;
+    for (const seg of segs.slice(0, -1)) {
+        const next = node[seg];
+        if (next === undefined)
+            node[seg] = {};
+        else if (!isObj(next))
+            return;
+        node = node[seg];
+    }
+    node[segs[segs.length - 1]] = value;
+}
+/** 按点路径删除键（路径不存在时无操作）。 */
+function deleteDeep(obj, path) {
+    const segs = path.split(".");
+    let node = obj;
+    for (const seg of segs.slice(0, -1)) {
+        if (!isObj(node))
+            return;
+        node = node[seg];
+    }
+    if (isObj(node))
+        delete node[segs[segs.length - 1]];
+}
+/** 由 issue 类型与结构字段生成说明；不用 zod 的 message（自定义消息可能拼入输入值）。 */
+function issueMessage(i) {
+    switch (i.code) {
+        case "invalid_type":
+            return `expected ${i.expected}`;
+        case "too_small":
+            return `too small (minimum ${String(i.minimum)})`;
+        case "too_big":
+            return `too big (maximum ${String(i.maximum)})`;
+        case "invalid_format":
+            return `invalid ${i.format}`;
+        case "not_multiple_of":
+            return `not a multiple of ${String(i.divisor)}`;
+        case "unrecognized_keys":
+            return "unrecognized keys";
+        case "invalid_union":
+            return "no union member matched";
+        case "invalid_key":
+            return "invalid key";
+        case "invalid_element":
+            return "invalid element";
+        default:
+            return "invalid value";
+    }
+}
+export function toIssues(error) {
+    return error.issues.map((i) => ({
+        path: i.path.map(String).join("."),
+        message: issueMessage(i),
+    }));
+}
+/** 插件组织级 schema 中标记 secret 的叶子点路径（对象路径之外的 secret 已在插件加载时拒绝）。 */
+function secretPaths(schema) {
+    return configFields(schema)
+        .filter((f) => f.meta?.secret)
+        .map((f) => f.path);
+}
+/**
+ * Org-level extension config: enablement and the `config.org` config stored per org.
+ * The non-secret part is stored in `capybara.extension_org_configs.config`; each secret field is
+ * encrypted separately in `capybara.secrets` (namespace `kernel`, key `plugin-config:<plugin>:<path>`),
+ * written in the same transaction as the config row.
+ * No in-process state: every call reads PG, safe with multiple replicas.
+ */
+export class OrgExtensionConfigs {
+    db;
+    keyring;
+    host;
+    hooks;
+    constructor(db, keyring, host, hooks = {}) {
+        this.db = db;
+        this.keyring = keyring;
+        this.host = host;
+        this.hooks = hooks;
+    }
+    /** 把一份组织配置里的密钥值交给 onSecrets（无回调或无密钥时无操作）；调用方须在事务提交后调用。 */
+    reportSecrets(found) {
+        if (!found || !this.hooks.onSecrets)
+            return;
+        const values = secretValues(found.schema, found.config);
+        if (values.length > 0)
+            this.hooks.onSecrets(values);
+    }
+    /** `REPEATABLE READ` 只读事务：配置行与密钥来自同一个快照，不会读到跨两次提交的混合状态。 */
+    snapshot(fn) {
+        return this.db
+            .transaction()
+            .setIsolationLevel("repeatable read")
+            .setAccessMode("read only")
+            .execute(fn);
+    }
+    /**
+     * 列出所有已加载插件在该组织下的状态（按加载顺序）；无记录时 enabled=false、config=null。
+     * 之后是已安装但此刻没加载的插件（部署上停用等），`available: false`，按名字排序。
+     */
+    async list(orgId) {
+        const installed = (await this.hooks.installed?.()) ?? [];
+        return this.snapshot(async (t) => {
+            const rows = await t
+                .selectFrom("extension_org_configs")
+                .select(["plugin", "enabled", "config"])
+                .where("org_id", "=", orgId)
+                .execute();
+            await this.hooks.afterConfigRowRead?.();
+            const setKeys = await this.setSecretKeys(t, orgId);
+            // Required bootstrap plugins are listed enabled (no org config row needed, spec §7)
+            const required = await requiredExtensions(t);
+            const loaded = this.host.manifests();
+            const views = loaded.map((m) => this.view(m, rows.find((r) => r.plugin === m.name), setKeys, required.has(m.name)));
+            const names = new Set(loaded.map((m) => m.name));
+            const unavailable = installed
+                .filter((i) => !names.has(i.name))
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .map((i) => ({
+                plugin: i.name,
+                version: i.version,
+                enabled: required.has(i.name) || (rows.find((r) => r.plugin === i.name)?.enabled ?? false),
+                configurable: false,
+                config: null,
+                secrets: [],
+                permissions: [],
+                orgConfigSchema: null,
+                available: false,
+                required: required.has(i.name),
+            }));
+            return [...views, ...unavailable];
+        });
+    }
+    /**
+     * Writes enablement and / or config. The actor's role is re-read under the org row lock (needs
+     * `org.extensions.manage`).
+     * - Extension not loaded -> `extension.not_found`; `config` given but the extension has no
+     *   `config.org` -> `extension.no_org_config`; `enabled: false` for a required bootstrap plugin
+     *   -> `extension.required` (it stays enabled in every org; its config can still be written).
+     * - Non-secret fields are replaced as a whole by the given value; secret fields keep the old value
+     *   when omitted, `null` clears, any other value is the new value.
+     * - The merged full config (or, without `config`, the existing config when the result is enabled)
+     *   does not satisfy the schema -> `extension.config_invalid`.
+     */
+    async put(orgId, plugin, input, actorAccountId, actorTokenId, opts = {}) {
+        const manifest = this.manifest(plugin);
+        const schema = manifest.config?.org;
+        if (input.config !== undefined && !schema) {
+            throw new ApiError("extension.no_org_config", `Extension ${plugin} has no organization config`);
+        }
+        let seen;
+        const view = await this.db.transaction().execute(async (t) => {
+            await lockOrgAndAuthorize(t, orgId, actorAccountId, "org.extensions.manage");
+            const row = await t
+                .selectFrom("extension_org_configs")
+                .select(["enabled", "config"])
+                .where("plugin", "=", plugin)
+                .where("org_id", "=", orgId)
+                .executeTakeFirst();
+            const required = (await requiredExtensions(t)).has(plugin);
+            if (required && input.enabled === false)
+                throw requiredError(plugin);
+            if (opts.ifDisabled && (row?.enabled === true || required)) {
+                opts.ifDisabled.skipped = true;
+                await opts.inTransaction?.(t, true);
+                return this.view(manifest, row, await this.setSecretKeys(t, orgId), required);
+            }
+            // A required plugin is enabled whatever the row said (it may predate `required`)
+            const enabled = required || (input.enabled ?? row?.enabled ?? false);
+            // 新启用来自企业目录的插件：按条目策略与授予复核（C22；已启用的不受影响）
+            if (input.enabled === true && row?.enabled !== true && !required) {
+                // 插件自己的条目 disabled 是总开关，任何途径都不能新启用（裁决 M-5）
+                const killed = await disabledPluginItems(t, [plugin]);
+                if (killed.length > 0)
+                    throw pluginItemDisabled(killed);
+                // 经某个条目安装：只看该条目（应用里的插件按应用条目，C22）；直接启用：全部来源里最严格的生效
+                if (opts.viaItem !== undefined) {
+                    await assertItemInstallable(t, orgId, opts.viaItem, opts.approvedBy ?? opts.viaItem);
+                }
+                else
+                    await assertPluginSourcesInstallable(t, orgId, plugin);
+            }
+            if (input.enabled === true)
+                await this.assertDependenciesEnabled(t, orgId, manifest);
+            else if (input.enabled === false && !input.force) {
+                await this.assertNoEnabledDependents(t, orgId, manifest);
+            }
+            let plain = row?.config ?? null;
+            let changed = [];
+            if (schema) {
+                const secrets = createSecrets(t, this.keyring, SECRETS_NAMESPACE);
+                const paths = secretPaths(schema);
+                const before = structuredClone(plain ?? {});
+                for (const p of paths) {
+                    const v = await secrets.get(orgId, secretKey(plugin, p));
+                    if (v !== null)
+                        setDeep(before, p, JSON.parse(v));
+                }
+                let next;
+                if (input.config !== undefined) {
+                    next = structuredClone(input.config);
+                    for (const p of paths) {
+                        const v = getPath(input.config, p);
+                        if (v === null)
+                            deleteDeep(next, p);
+                        else if (v === undefined) {
+                            const old = getPath(before, p);
+                            if (old !== undefined)
+                                setDeep(next, p, old);
+                        }
+                    }
+                }
+                else {
+                    next = before;
+                }
+                if (input.config !== undefined || enabled) {
+                    const r = schema.safeParse(next);
+                    if (!r.success) {
+                        throw new ApiError("extension.config_invalid", `Invalid organization config for extension ${plugin}`, toIssues(r.error));
+                    }
+                    next = r.data;
+                }
+                seen = { schema, config: next };
+                if (input.config !== undefined) {
+                    changed = changedPaths(schema, before, next);
+                    plain = structuredClone(next);
+                    for (const p of paths) {
+                        const v = getPath(next, p);
+                        deleteDeep(plain, p);
+                        if (v === undefined)
+                            await secrets.delete(orgId, secretKey(plugin, p));
+                        else
+                            await secrets.set(orgId, secretKey(plugin, p), JSON.stringify(v));
+                    }
+                }
+            }
+            // 当前 schema 中已不存在的密钥路径：同一事务内清掉遗留的密文行
+            const live = new Set((schema ? secretPaths(schema) : []).map((p) => secretKey(plugin, p)));
+            const prefix = secretKey(plugin, "");
+            const cleanup = createSecrets(t, this.keyring, SECRETS_NAMESPACE);
+            for (const key of await this.setSecretKeys(t, orgId)) {
+                if (key.startsWith(prefix) && !live.has(key))
+                    await cleanup.delete(orgId, key);
+            }
+            await t
+                .insertInto("extension_org_configs")
+                .values({
+                plugin,
+                org_id: orgId,
+                enabled,
+                config: plain === null ? null : JSON.stringify(plain),
+                updated_by: actorAccountId,
+            })
+                .onConflict((oc) => oc.columns(["plugin", "org_id"]).doUpdateSet({
+                enabled,
+                config: plain === null ? null : JSON.stringify(plain),
+                updated_by: actorAccountId,
+                updated_at: new Date(),
+            }))
+                .execute();
+            await audit(t, {
+                actorAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "org.plugin_config.updated",
+                target: plugin,
+                detail: {
+                    enabled,
+                    changedPaths: changed,
+                    ...(opts.viaItem !== undefined && { catalogItemId: opts.viaItem }),
+                },
+            });
+            await opts.inTransaction?.(t, false);
+            // 在同一事务里读回，返回值就是刚提交的状态
+            const saved = await t
+                .selectFrom("extension_org_configs")
+                .select(["plugin", "enabled", "config"])
+                .where("plugin", "=", plugin)
+                .where("org_id", "=", orgId)
+                .executeTakeFirst();
+            return this.view(manifest, saved, await this.setSecretKeys(t, orgId), required);
+        });
+        // 事务已提交：回滚的写入不会走到这里
+        this.reportSecrets(seen);
+        await this.hooks.afterPut?.(orgId, plugin, view.enabled);
+        return view;
+    }
+    /**
+     * 读取并解密某插件在该组织下的完整配置（供运行时按组织构造插件实例）。
+     * A required bootstrap plugin is enabled without a row (its stored config, or `{}`, is validated).
+     * 无记录 → undefined；插件无 `config.org` 或已停用（`enabled=false`，不校验、不读密钥）时 `config` 为 null。
+     * 配置行与密钥在同一个 `REPEATABLE READ` 只读事务里读取。
+     * 已存配置不再满足 schema（如插件升级后）→ 抛 Error，信息含插件名、组织 ID 与出错路径（不含值）。
+     */
+    async get(orgId, plugin) {
+        const manifest = this.manifest(plugin);
+        const result = await this.snapshot(async (t) => {
+            const row = await t
+                .selectFrom("extension_org_configs")
+                .select(["enabled", "config"])
+                .where("plugin", "=", plugin)
+                .where("org_id", "=", orgId)
+                .executeTakeFirst();
+            await this.hooks.afterConfigRowRead?.();
+            const required = (await requiredExtensions(t)).has(plugin);
+            if (!row && !required)
+                return undefined;
+            const enabled = required || row?.enabled === true;
+            const schema = manifest.config?.org;
+            // 已停用的插件不会被实例化：不校验（可能是升级前存下的旧配置），也不解密密钥
+            if (!schema || !enabled)
+                return { enabled, config: null };
+            return this.decode(t, orgId, plugin, schema, row?.config ?? {});
+        });
+        // 只读快照已结束；config 非 null 意味着插件有 org schema 且已解密
+        const schema = manifest.config?.org;
+        if (schema && result?.config != null)
+            this.reportSecrets({ schema, config: result.config });
+        return result;
+    }
+    async decode(t, orgId, plugin, schema, stored) {
+        const full = structuredClone(stored);
+        const secrets = createSecrets(t, this.keyring, SECRETS_NAMESPACE);
+        for (const p of secretPaths(schema)) {
+            const v = await secrets.get(orgId, secretKey(plugin, p));
+            if (v !== null)
+                setDeep(full, p, JSON.parse(v));
+        }
+        const r = schema.safeParse(full);
+        if (!r.success) {
+            const detail = toIssues(r.error)
+                .map((i) => `${i.path || "<root>"}: ${i.message}`)
+                .join("; ");
+            throw new Error(`plugin ${plugin}: stored organization config for org ${orgId} is invalid: ${detail}`);
+        }
+        return { enabled: true, config: r.data };
+    }
+    /**
+     * 该组织里已启用、且所 requires 的按组织启用的能力只剩这个插件提供的插件（停用它会让它们失去依赖）。
+     * 在调用方事务里读（应用卸载 / 回滚前判断是否保留）。
+     */
+    async enabledDependents(t, orgId, plugin) {
+        const manifest = this.host.manifests().find((m) => m.name === plugin);
+        if (!manifest)
+            return [];
+        const provided = manifest.provides.filter((r) => this.isOrgScoped(r));
+        if (provided.length === 0)
+            return [];
+        const enabled = await this.enabledSet(t, orgId);
+        if (!enabled.has(plugin))
+            return [];
+        const out = new Set();
+        for (const ref of provided) {
+            if (this.enabledProviders(enabled, ref, plugin).length > 0)
+                continue;
+            for (const m of this.host.manifests()) {
+                if (m.name === plugin || !enabled.has(m.name))
+                    continue;
+                if ((m.requires ?? []).includes(ref))
+                    out.add(m.name);
+            }
+        }
+        return [...out].sort();
+    }
+    /**
+     * 在调用方事务里停用（应用安装的回滚与卸载用；调用方已锁组织行并复核角色）：不检查依赖方，配置保留，
+     * 审计 `org.plugin_config.updated`（带 reason）。提交后调用方须再调 {@link afterDisable}。
+     */
+    async disableIn(t, orgId, plugin, actorAccountId, reason) {
+        // A required bootstrap plugin stays enabled in every org
+        if ((await requiredExtensions(t)).has(plugin))
+            return false;
+        const r = await t
+            .updateTable("extension_org_configs")
+            .set({ enabled: false, updated_by: actorAccountId, updated_at: new Date() })
+            .where("plugin", "=", plugin)
+            .where("org_id", "=", orgId)
+            .where("enabled", "=", true)
+            .returning("plugin")
+            .executeTakeFirst();
+        if (!r)
+            return false;
+        await audit(t, {
+            actorAccountId,
+            orgId,
+            action: "org.plugin_config.updated",
+            target: plugin,
+            detail: { enabled: false, changedPaths: [], reason },
+        });
+        return true;
+    }
+    /** {@link disableIn} 的事务提交之后：通知停用（断开该插件的渠道连接等）。 */
+    async afterDisable(orgId, plugin) {
+        await this.hooks.afterPut?.(orgId, plugin, false);
+    }
+    /** 该组织已启用的插件名（只含当前已加载的插件；待批准的不算；必需的引导插件始终算启用）。 */
+    async enabledSet(t, orgId) {
+        const rows = await enabledExtensionsQuery(t, orgId).execute();
+        const loaded = new Set(this.host.manifests().map((m) => m.name));
+        return new Set(rows.map((r) => r.plugin).filter((n) => loaded.has(n)));
+    }
+    /** 引用是否为按组织启用的能力。 */
+    isOrgScoped(ref) {
+        return EXTENSION_POINTS[parseExtensionPoint(ref).name]?.orgScoped === true;
+    }
+    /** 该组织内（已启用、已加载、非 `except`）提供完整引用（含主版本）的插件。 */
+    enabledProviders(enabled, ref, except) {
+        return this.host
+            .manifests()
+            .filter((m) => m.name !== except && enabled.has(m.name) && m.provides.includes(ref))
+            .map((m) => m.name);
+    }
+    /** 启用前：A `requires` 的每个 orgScoped 能力（按主版本），该组织须至少有一个已启用的提供方。 */
+    async assertDependenciesEnabled(t, orgId, manifest) {
+        const needed = (manifest.requires ?? []).filter((r) => this.isOrgScoped(r));
+        if (needed.length === 0)
+            return;
+        const enabled = await this.enabledSet(t, orgId);
+        const missing = needed.filter((r) => this.enabledProviders(enabled, r, manifest.name).length === 0);
+        if (missing.length > 0) {
+            throw new ApiError("extension.dependency_missing", `Extension ${manifest.name} requires extension points with no enabled provider in this organization: ${missing.join(", ")}`, missing.map((extensionPoint) => ({ extensionPoint })));
+        }
+    }
+    /** 停用前：若停用后某个已启用的插件所 requires 的 orgScoped 能力（按主版本）再无已启用的提供方，拒绝。 */
+    async assertNoEnabledDependents(t, orgId, manifest) {
+        const provided = manifest.provides.filter((r) => this.isOrgScoped(r));
+        if (provided.length === 0)
+            return;
+        const enabled = await this.enabledSet(t, orgId);
+        if (!enabled.has(manifest.name))
+            return;
+        const dependents = new Map();
+        for (const ref of provided) {
+            if (this.enabledProviders(enabled, ref, manifest.name).length > 0)
+                continue;
+            for (const m of this.host.manifests()) {
+                if (m.name === manifest.name || !enabled.has(m.name))
+                    continue;
+                if ((m.requires ?? []).includes(ref)) {
+                    dependents.set(`${m.name}\0${ref}`, { plugin: m.name, extensionPoint: ref });
+                }
+            }
+        }
+        if (dependents.size > 0) {
+            const list = [...dependents.values()];
+            throw new ApiError("extension.has_dependents", `Extension ${manifest.name} is required by enabled extensions in this organization: ${[...new Set(list.map((d) => d.plugin))].join(", ")} (pass force to disable anyway)`, list);
+        }
+    }
+    manifest(plugin) {
+        const m = this.host.manifests().find((x) => x.name === plugin);
+        if (!m)
+            throw new ApiError("extension.not_found", `Extension ${plugin} is not installed`);
+        return m;
+    }
+    permissionsOf(plugin) {
+        const set = this.host.permissionSet(plugin);
+        if (!set)
+            throw new ApiError("extension.not_found", `Extension ${plugin} is not installed`);
+        return set;
+    }
+    view(m, row, setKeys, required) {
+        const schema = m.config?.org;
+        const paths = schema ? secretPaths(schema) : [];
+        let config = null;
+        if (schema && row?.config) {
+            config = structuredClone(row.config);
+            for (const p of paths)
+                deleteDeep(config, p);
+        }
+        return {
+            plugin: m.name,
+            version: m.version,
+            enabled: required || (row?.enabled ?? false),
+            configurable: schema !== undefined,
+            config,
+            secrets: paths.map((p) => ({ path: p, set: setKeys.has(secretKey(m.name, p)) })),
+            permissions: permissionGroups(this.permissionsOf(m.name)),
+            orgConfigSchema: schema ? orgJsonSchema(schema) : null,
+            available: true,
+            required,
+        };
+    }
+    /** 该组织在 `kernel` 命名空间下已设置的插件配置密钥键（不解密）。 */
+    async setSecretKeys(db, orgId) {
+        const rows = await db
+            .selectFrom("secrets")
+            .select("key")
+            .where("namespace", "=", SECRETS_NAMESPACE)
+            .where("org_id", "=", orgId)
+            .where("key", "like", "plugin-config:%")
+            .execute();
+        return new Set(rows.map((r) => r.key));
+    }
+}
+const requiredError = (plugin) => new ApiError("extension.required", `Extension ${plugin} is required by this deployment (a bootstrap plugin): it is enabled in every organization and cannot be disabled`);

package/dist/extensions/package.d.ts

@@ -0,0 +1,115 @@
+import { type PluginExtensionSection } from "@capybara-hq/plugin-sdk";
+import { ApiError } from "../errors.js";
+import { HOST_ZOD_VERSION, type PackageTgzLimits } from "../packages/tgz.js";
+import { type PermissionSet } from "./permission-set.js";
+/**
+ * Reading and validating an extension package: a plugin tgz (`readPluginPackage`,
+ * `catalog/plugin-package.ts`: unpacking by the rules of `packages/tgz.ts`, plugin.json, the
+ * package.json rules of plugin-sdk `validatePluginPackageJsonFor`, the pre-0.1.0 format rejected)
+ * with an `extension` section. On top of the plugin rules:
+ *
+ * - import 白名单：用 es-module-lexer（2.3.2，固定版本）静态分析 entry 及其包内相对 import 到的模块：
+ *   静态 import / `export ... from` / 字面量动态 `import()` 只许 `node:*`、宿主两包（含子路径）与包内相对路径；
+ *   **非字面量的动态 `import()` 拒绝**。相对路径解析后必须仍在包内、指向包里存在的 `.mjs` / `.js`，并同样被扫描。
+ * - `require`：ESM 里没有 `require` 绑定，bundle 只能经 `node:module` 的 `createRequire` 得到它（打包工具的横幅
+ *   就是这样给打进来的 CJS 依赖用的）。这里**不**静态分析 `require(...)`：一是 bundle 里大量 `require("x")`
+ *   字样出现在字符串 / 代码生成模板里（实测 connector-mcp 里 ajv 的模板、object-store-s3 的报错文案），正则必然误报，
+ *   为此在安装路径上引入完整 JS 解析器不值得；二是插件本来就以批准过的代码在进程内运行（权限是治理而非沙箱），
+ *   拦 `require` 拦不住 `process.getBuiltinModule`。打包工具在构建时已保证 require 只指向 `node:*` 与宿主包
+ *   （其余全部打进 bundle）；插件目录不在宿主 `node_modules` 的上游路径里，漏打的 `require("x")` 加载时找不到，
+ *   安装记录转为 failed。
+ */
+/** Limits on unpacking an extension package (the shared tgz limits). */
+export declare const EXTENSION_PACKAGE_LIMITS: {
+    readonly maxUnpackedBytes: number;
+    readonly maxEntries: 5000;
+    readonly maxPackageJsonBytes: number;
+};
+export { HOST_ZOD_VERSION };
+/** Unpack limits: `maxBytes` is `packages.maxBytes`; the rest default to {@link EXTENSION_PACKAGE_LIMITS}. */
+export type ExtensionPackageLimits = PackageTgzLimits;
+/**
+ * Codes of {@link ExtensionPackageError}: an invalid package, a tgz in the pre-0.1.0 format, or a
+ * plugin without an extension (nothing to install on the deployment).
+ */
+export type ExtensionPackageErrorCode = "extension.package_invalid" | "extension.legacy_format" | "extension.no_extension";
+/** The extension package is invalid; `issues` lists the problems (English, shown to the admin). */
+export declare class ExtensionPackageError extends Error {
+    readonly code: ExtensionPackageErrorCode;
+    readonly issues: string[];
+    constructor(issues: string[], code?: ExtensionPackageErrorCode);
+}
+/** The API error for an {@link ExtensionPackageError} (its code, message and issues as details). */
+export declare function extensionPackageApiError(e: ExtensionPackageError): ApiError;
+/**
+ * The extension of a read package: the plugin's {@link PluginExtensionSection} (paths start with
+ * `./`; resolve them with {@link packagePath}) plus the plugin's name and version.
+ */
+export type ExtensionPackageSection = PluginExtensionSection & {
+    name: string;
+    version: string;
+};
+/** A read and validated extension package. Paths are relative to the package root (no `package/`). */
+export interface ExtensionPackage {
+    /** Hex sha256 of the whole tgz. */
+    sha256: string;
+    /** tgz bytes. */
+    size: number;
+    packageJson: Record<string, unknown>;
+    section: ExtensionPackageSection;
+    files: {
+        path: string;
+        size: number;
+    }[];
+    /** Migration-named SQL directly in the `extension.migrations` directory, sorted by file name. */
+    migrationSql: {
+        file: string;
+        sql: string;
+    }[];
+}
+/** Options of {@link readExtensionPackage}; `hostZodVersion` defaults to {@link HOST_ZOD_VERSION}. */
+export interface ReadExtensionPackageOptions extends ExtensionPackageLimits {
+    hostSdkVersion: string;
+    hostZodVersion?: string;
+}
+/**
+ * Reads and validates an extension package without running any code from it: a plugin tgz
+ * (`readPluginPackage`) with an `extension` section, whose entry's module graph passes the import
+ * rules (file header) and whose `extension.migrations` SQL is collected. Invalid ->
+ * {@link ExtensionPackageError} (listing every problem it can find; problems while unpacking stop
+ * at the first): `extension.legacy_format` for the pre-0.1.0 format, `extension.no_extension` for a
+ * plugin without an extension, otherwise `extension.package_invalid`.
+ */
+export declare function readExtensionPackage(bytes: Uint8Array, opts: ReadExtensionPackageOptions): Promise<ExtensionPackage>;
+/**
+ * The package's permission set from the static manifest and the migration SQL only (review runs no
+ * extension code), in the same shape as `computePermissionSet` on the real module (config fields
+ * keep only path / secret).
+ */
+export declare function permissionSetOfPackage(p: ExtensionPackage): PermissionSet;
+/**
+ * Same as {@link permissionSetOfPackage}, from the extension section and the migration SQL (the host
+ * uses it on the locally synced package for the permission gate without importing the module: no
+ * extension code, top-level code included, runs before approval).
+ */
+export declare function permissionSetOfSection(section: Pick<PluginExtensionSection, "manifest">, migrationSql: {
+    file: string;
+    sql: string;
+}[]): PermissionSet;
+/**
+ * Reads the migration SQL in `extension.migrations` under the locally unpacked directory `root` (not
+ * recursive, only files with migration names, sorted by name), in the same shape as the
+ * `migrationSql` of {@link readExtensionPackage}; empty when no migrations are declared.
+ */
+export declare function readMigrationSql(root: string, section: Pick<PluginExtensionSection, "migrations">): Promise<{
+    file: string;
+    sql: string;
+}[]>;
+/**
+ * Unpacks the package into `dir` (dropping the `package/` prefix). `dir` must not exist or be empty;
+ * the unpack rules and limits are the same as {@link readExtensionPackage} (paths, file types, entry
+ * count and unpacked size; pass the same `limits`, i.e. `packages.maxBytes`), and the package should
+ * have been validated with it first. Files 0644, directories 0755, written with `wx` (no overwrite,
+ * no following existing links).
+ */
+export declare function extractExtensionPackage(bytes: Uint8Array, dir: string, limits: ExtensionPackageLimits): Promise<void>;