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

package/dist/extensions/package.js

@@ -0,0 +1,246 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, posix, relative, resolve as resolvePath } from "node:path";
+import { checkEntryImports, isSafePackagePath, PLUGIN_MANIFEST_FILE, } from "@capybara-hq/plugin-sdk";
+import { init as lexerInit, parse as lexerParse } from "es-module-lexer";
+import { PluginPackageError, readPluginPackage } from "../catalog/plugin-package.js";
+import { pluginSchemaName } from "../ctx/create-ctx.js";
+import { MIGRATION_FILE_RE } from "../db/migrator.js";
+import { ApiError } from "../errors.js";
+import { HOST_ZOD_VERSION, PACKAGE_TGZ_LIMITS, PackageTgzError, packagePath, unpackPackageTgz, } from "../packages/tgz.js";
+import { buildPermissionSet, parseCreatedTables } from "./permission-set.js";
+import { migrationWarnings, warningsDigest } from "./permission-view.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 const EXTENSION_PACKAGE_LIMITS = PACKAGE_TGZ_LIMITS;
+export { HOST_ZOD_VERSION };
+/** The extension package is invalid; `issues` lists the problems (English, shown to the admin). */
+export class ExtensionPackageError extends Error {
+    code;
+    issues;
+    constructor(issues, code = "extension.package_invalid") {
+        super(code === "extension.package_invalid"
+            ? `Invalid plugin package: ${issues[0] ?? "unknown problem"}`
+            : (issues[0] ?? code));
+        this.name = "ExtensionPackageError";
+        this.code = code;
+        this.issues = issues;
+    }
+}
+/** The API error for an {@link ExtensionPackageError} (its code, message and issues as details). */
+export function extensionPackageApiError(e) {
+    return new ApiError(e.code, e.message, e.issues);
+}
+const fail = (issue) => {
+    throw new ExtensionPackageError([issue]);
+};
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+const utf8 = (path, data) => {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(data);
+    }
+    catch {
+        return fail(`${path} is not valid UTF-8 text`);
+    }
+};
+/** 扫描一个模块的 import（es-module-lexer）；`import.meta` 不算 import。 */
+function scanImports(path, code) {
+    let imports;
+    try {
+        [imports] = lexerParse(code, path);
+    }
+    catch (e) {
+        return fail(`${path} is not valid ES module syntax: ${errMsg(e)}`);
+    }
+    const out = [];
+    for (const i of imports) {
+        if (i.d === -2)
+            continue; // import.meta
+        const dynamic = i.d > -1;
+        out.push({ name: i.n ?? "", dynamic, literal: i.n !== undefined });
+    }
+    return out;
+}
+/** 从 entry 出发，沿包内相对 import 逐个扫描，汇总问题。 */
+function checkModuleGraph(entry, byPath) {
+    const issues = [];
+    const queue = [entry];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const path = queue.shift();
+        if (visited.has(path))
+            continue;
+        visited.add(path);
+        const specs = scanImports(path, utf8(path, byPath.get(path)));
+        for (const msg of checkEntryImports(specs))
+            issues.push(`${path}: ${msg}`);
+        for (const s of specs) {
+            if (!s.name.startsWith("./") && !s.name.startsWith("../"))
+                continue;
+            const target = posix.normalize(posix.join(posix.dirname(path), s.name));
+            if (target.startsWith("../") || target === ".." || !isSafePackagePath(target)) {
+                issues.push(`${path}: import "${s.name}" points outside the package`);
+                continue;
+            }
+            if (!byPath.has(target)) {
+                issues.push(`${path}: import "${s.name}" not found in the package`);
+                continue;
+            }
+            if (!target.endsWith(".mjs") && !target.endsWith(".js")) {
+                issues.push(`${path}: import "${s.name}" must point to a .mjs or .js module`);
+                continue;
+            }
+            queue.push(target);
+        }
+    }
+    return issues;
+}
+/** Maps an error of `readPluginPackage` to the extension package error. */
+const fromPluginPackageError = (e) => new ExtensionPackageError(e.issues, e.code === "catalog.legacy_format" ? "extension.legacy_format" : "extension.package_invalid");
+/**
+ * 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 async function readExtensionPackage(bytes, opts) {
+    let plugin;
+    try {
+        plugin = await readPluginPackage(bytes, opts);
+    }
+    catch (e) {
+        if (e instanceof PluginPackageError)
+            throw fromPluginPackageError(e);
+        throw e;
+    }
+    const { manifest, files } = plugin;
+    const ext = manifest.extension;
+    if (ext === undefined) {
+        throw new ExtensionPackageError([
+            `plugin ${manifest.name} has no extension (no "extension" in ${PLUGIN_MANIFEST_FILE}); import it into the catalog instead`,
+        ], "extension.no_extension");
+    }
+    await lexerInit;
+    const issues = checkModuleGraph(packagePath(ext.entry), files);
+    const migrationSql = [];
+    if (ext.migrations !== undefined) {
+        const dir = packagePath(ext.migrations);
+        for (const [path, data] of files) {
+            if (!path.startsWith(`${dir}/`))
+                continue;
+            const file = path.slice(dir.length + 1);
+            if (file.includes("/") || !MIGRATION_FILE_RE.test(file))
+                continue;
+            migrationSql.push({ file, sql: utf8(path, data) });
+        }
+        migrationSql.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+    }
+    if (issues.length > 0)
+        throw new ExtensionPackageError(issues);
+    return {
+        sha256: plugin.sha256,
+        size: plugin.size,
+        packageJson: plugin.packageJson,
+        section: { ...ext, name: manifest.name, version: manifest.version },
+        files: [...files].map(([path, data]) => ({ path, size: data.byteLength })),
+        migrationSql,
+    };
+}
+/**
+ * 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 function permissionSetOfPackage(p) {
+    return permissionSetOfSection(p.section, p.migrationSql);
+}
+/**
+ * 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 function permissionSetOfSection(section, migrationSql) {
+    const m = section.manifest;
+    const schema = pluginSchemaName(m.name);
+    const tables = migrationSql.flatMap((f) => parseCreatedTables(f.sql, schema));
+    const strip = (fs) => fs.map((f) => ({ path: f.path, secret: f.secret }));
+    return buildPermissionSet({
+        provides: m.provides,
+        requires: m.requires,
+        optional: m.optional,
+        config: { deployment: strip(m.config.deployment), org: strip(m.config.org) },
+        tables,
+        permissions: m.permissions,
+        warningsDigest: warningsDigest(migrationWarnings(migrationSql, m.name)),
+    });
+}
+/**
+ * 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 async function readMigrationSql(root, section) {
+    if (section.migrations === undefined)
+        return [];
+    const dir = resolvePath(root, packagePath(section.migrations));
+    const names = (await readdir(dir)).filter((f) => MIGRATION_FILE_RE.test(f)).sort();
+    const out = [];
+    for (const file of names)
+        out.push({ file, sql: await readFile(resolvePath(dir, file), "utf8") });
+    return out;
+}
+/**
+ * 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 async function extractExtensionPackage(bytes, dir, limits) {
+    let files;
+    try {
+        files = await unpackPackageTgz(bytes, limits);
+    }
+    catch (e) {
+        if (e instanceof PackageTgzError)
+            throw new ExtensionPackageError(e.issues);
+        throw e;
+    }
+    const root = resolvePath(dir);
+    let existing = [];
+    try {
+        existing = await readdir(root);
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    if (existing.length > 0)
+        throw new Error(`extract target ${root} is not empty`);
+    await mkdir(root, { recursive: true, mode: 0o755 });
+    for (const f of files) {
+        const target = resolvePath(root, f.path);
+        const rel = relative(root, target);
+        if (rel.startsWith("..") || rel === "")
+            fail(`${f.path}: unsafe path`);
+        await mkdir(dirname(target), { recursive: true, mode: 0o755 });
+        await writeFile(target, f.data, { flag: "wx", mode: 0o644 });
+    }
+}

package/dist/extensions/permission-set.d.ts

@@ -0,0 +1,117 @@
+import type { ExtensionManifest, ExtensionPermissions } from "@capybara-hq/plugin-sdk";
+/** 一个配置字段：点路径（根即叶子时为空串）与是否密钥。 */
+export interface PermissionConfigField {
+    path: string;
+    secret: boolean;
+}
+/**
+ * Everything an extension uses (extension model 7.2), normalized and stored as the approved snapshot
+ * (`extension_permission_snapshots.permissions`). Every list is sorted and deduplicated; comparisons
+ * use stable string keys ({@link permissionKeys}).
+ */
+export interface PermissionSet {
+    provides: string[];
+    requires: string[];
+    optional: string[];
+    config: {
+        deployment: PermissionConfigField[];
+        org: PermissionConfigField[];
+    };
+    /** 插件迁移里 `CREATE TABLE` 的表名（插件自己 schema 下的不带前缀）。 */
+    tables: string[];
+    permissions: {
+        secrets: boolean;
+        storage: boolean;
+        http: {
+            method: string;
+            path: string;
+            public: boolean;
+        }[];
+        tools: string[];
+        hooks: string[];
+        /**
+         * Mount points with `policy` hooks (`permissions.policyHooks`, M-1). Deployment state reads it from
+         * the approved snapshot to fail calls closed where the plugin is not loaded. Absent when none are
+         * declared (and in older snapshots).
+         */
+        policyHooks?: string[];
+        /** 模型用途（label 只是展示文案，不参与比较）。 */
+        models: {
+            purpose: string;
+            kind: string;
+        }[];
+        network: string[];
+        /**
+         * 界面贡献（`permissions.ui`）：`views` 记入快照但不卡加载（升级时自动补进快照）；
+         * `embeds` 与其他权限一样卡加载。旧快照没有这一项（按空处理）。
+         */
+        ui: {
+            views: string[];
+            embeds: string[];
+        };
+    };
+    /**
+     * 安装记录包迁移警告的摘要（`warningsDigest`，Ruling P4）；没有警告或不是安装记录时省略。
+     * 记入快照：权限不变、警告变了同样要重新批准；没有摘要的旧快照遇到有警告的包同样要重新批准。
+     */
+    warningsDigest?: string;
+}
+/** 迁移警告摘要的权限键前缀（`migration.warnings:<摘要>`）。 */
+export declare const WARNINGS_KEY_PREFIX = "migration.warnings:";
+/**
+ * 解析 SQL 中 `CREATE [TEMP|UNLOGGED] TABLE [IF NOT EXISTS] [schema.]name` 的表名（按出现顺序，不去重）；
+ * 其他语句忽略。schema 等于 `ownSchema` 时去掉前缀（与不带前缀等价），其他 schema 保留 `schema.name`。
+ *
+ * 已知局限（够用即可，不是 SQL 解析器）：
+ * - 只看 `CREATE TABLE`：`ALTER TABLE ... RENAME TO` 改名后的新表名不会出现；视图 / 物化视图、
+ *   序列、函数等其他建对象语句不计入；
+ * - 不带引号的标识符只识别 ASCII（字母、数字、`_`、`$`），不带引号的非 ASCII 表名会被截断或漏掉；
+ * - 去注释不理会字符串字面量与 `$$` 块：字符串里的 `--` / `/*` 会被当作注释，字符串里的
+ *   `CREATE TABLE x` 文本会被误计。
+ */
+export declare function parseCreatedTables(sql: string, ownSchema: string): string[];
+/**
+ * 计算插件的权限集合：provides / requires / optional、两级配置字段（路径与是否密钥，经 `configFields` 遍历 zod schema）、
+ * 迁移 SQL 中创建的表、清单 `permissions` 各项；全部规范化排序。
+ * @param pluginDir 插件模块所在目录（`manifest.migrations` 相对它解析）。
+ */
+export declare function computePermissionSet(manifest: ExtensionManifest, pluginDir: string): Promise<PermissionSet>;
+/**
+ * 由已提取的各项拼出规范化的权限集合（排序去重）：{@link computePermissionSet}（真实模块）与
+ * 插件包的 `permissionSetOfPackage`（静态 manifest + 迁移 SQL）共用，保证两边同形。
+ */
+export declare function buildPermissionSet(input: {
+    provides: readonly string[];
+    requires?: readonly string[] | undefined;
+    optional?: readonly string[] | undefined;
+    config: {
+        deployment: PermissionConfigField[];
+        org: PermissionConfigField[];
+    };
+    tables: readonly string[];
+    permissions?: ExtensionPermissions | undefined;
+    warningsDigest?: string | undefined;
+}): PermissionSet;
+/**
+ * 权限集合的稳定字符串键（排序），如 `provides:channel@1`、`config.org.secret:apiKey`、`table:todos`、
+ * `permissions.tools:write`、`permissions.http.public:POST /events`、`ui.view:tasks`、`ui.embed:board`。
+ * 容忍旧快照缺字段（按空处理），快照格式演进时不会抛错。
+ */
+export declare function permissionKeys(set: PermissionSet): string[];
+/**
+ * Key prefix of a policy hook mount (manifest `permissions.policyHooks`): needs approval like any hook.
+ * Lower-case letters and dots only, as catalog permission keys require (`PERMISSION_KEY_RE`).
+ */
+export declare const POLICY_HOOK_KEY_PREFIX = "permissions.hooks.policy:";
+/** 渲染 schema 视图的权限键前缀：记入快照但不卡加载（见 {@link blockingKeys}）。 */
+export declare const UI_VIEW_KEY_PREFIX = "ui.view:";
+/**
+ * 新增项里需要批准（卡加载）的部分：除 `ui.view:*` 之外的全部。视图只是把插件已有的数据交给内核组件来画，
+ * 不给插件新能力（spec §4.1），升级多出视图时插件照常加载、快照自动补上。
+ */
+export declare function blockingKeys(added: readonly string[]): string[];
+/** 两份权限集合的差异（按 {@link permissionKeys}）；`prev` 为空（无快照）时全部算新增。 */
+export declare function diffPermissions(prev: PermissionSet | undefined, next: PermissionSet): {
+    added: string[];
+    removed: string[];
+};

package/dist/extensions/permission-set.js

@@ -0,0 +1,184 @@
+import { readdir, readFile } from "node:fs/promises";
+import { resolve as resolvePath } from "node:path";
+import { configFields } from "../config/fields.js";
+import { pluginSchemaName } from "../ctx/create-ctx.js";
+import { MIGRATION_FILE_RE } from "../db/migrator.js";
+/** 迁移警告摘要的权限键前缀（`migration.warnings:<摘要>`）。 */
+export const WARNINGS_KEY_PREFIX = "migration.warnings:";
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const sortedUnique = (xs) => [...new Set(xs ?? [])].sort(cmp);
+const IDENT = '(?:"(?:[^"]|"")+"|[A-Za-z_][A-Za-z0-9_$]*)';
+const CREATE_TABLE_RE = new RegExp(String.raw `\bcreate\s+(?:(?:global|local)\s+)?(?:(?:temp|temporary|unlogged)\s+)?table\s+(?:if\s+not\s+exists\s+)?(${IDENT}(?:\s*\.\s*${IDENT})?)`, "gi");
+/** 标识符规范化：带引号的去引号（`""` 还原为 `"`），不带引号的转小写（同 PG 规则）。 */
+const normIdent = (s) => s.startsWith('"') ? s.slice(1, -1).replaceAll('""', '"') : s.toLowerCase();
+/** 把一段 SQL 的 `--` 行注释与 `/* *\/` 块注释去掉（不处理字符串字面量里的注释符：够用即可）。 */
+const stripComments = (sql) => sql.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/--[^\n]*/g, " ");
+/**
+ * 解析 SQL 中 `CREATE [TEMP|UNLOGGED] TABLE [IF NOT EXISTS] [schema.]name` 的表名（按出现顺序，不去重）；
+ * 其他语句忽略。schema 等于 `ownSchema` 时去掉前缀（与不带前缀等价），其他 schema 保留 `schema.name`。
+ *
+ * 已知局限（够用即可，不是 SQL 解析器）：
+ * - 只看 `CREATE TABLE`：`ALTER TABLE ... RENAME TO` 改名后的新表名不会出现；视图 / 物化视图、
+ *   序列、函数等其他建对象语句不计入；
+ * - 不带引号的标识符只识别 ASCII（字母、数字、`_`、`$`），不带引号的非 ASCII 表名会被截断或漏掉；
+ * - 去注释不理会字符串字面量与 `$$` 块：字符串里的 `--` / `/*` 会被当作注释，字符串里的
+ *   `CREATE TABLE x` 文本会被误计。
+ */
+export function parseCreatedTables(sql, ownSchema) {
+    const out = [];
+    for (const m of stripComments(sql).matchAll(CREATE_TABLE_RE)) {
+        const parts = m[1].match(new RegExp(IDENT, "g")) ?? [];
+        const names = parts.map(normIdent);
+        if (names.length === 2 && names[0] === ownSchema)
+            out.push(names[1]);
+        else
+            out.push(names.join("."));
+    }
+    return out;
+}
+function fieldsOf(schema) {
+    if (!schema)
+        return [];
+    return configFields(schema)
+        .map((f) => ({ path: f.path, secret: f.meta?.secret === true }))
+        .sort((a, b) => cmp(a.path, b.path));
+}
+/**
+ * 计算插件的权限集合：provides / requires / optional、两级配置字段（路径与是否密钥，经 `configFields` 遍历 zod schema）、
+ * 迁移 SQL 中创建的表、清单 `permissions` 各项；全部规范化排序。
+ * @param pluginDir 插件模块所在目录（`manifest.migrations` 相对它解析）。
+ */
+export async function computePermissionSet(manifest, pluginDir) {
+    const tables = [];
+    if (manifest.migrations) {
+        const dir = resolvePath(pluginDir, manifest.migrations);
+        const schema = pluginSchemaName(manifest.name);
+        try {
+            const names = (await readdir(dir)).filter((f) => MIGRATION_FILE_RE.test(f)).sort();
+            for (const n of names) {
+                tables.push(...parseCreatedTables(await readFile(resolvePath(dir, n), "utf8"), schema));
+            }
+        }
+        catch (e) {
+            throw new Error(`plugin ${manifest.name}: cannot read migrations at "${dir}": ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+        }
+    }
+    return buildPermissionSet({
+        provides: manifest.provides,
+        requires: manifest.requires,
+        optional: manifest.optional,
+        config: {
+            deployment: fieldsOf(manifest.config?.deployment),
+            org: fieldsOf(manifest.config?.org),
+        },
+        tables,
+        permissions: manifest.permissions,
+    });
+}
+/**
+ * 由已提取的各项拼出规范化的权限集合（排序去重）：{@link computePermissionSet}（真实模块）与
+ * 插件包的 `permissionSetOfPackage`（静态 manifest + 迁移 SQL）共用，保证两边同形。
+ */
+export function buildPermissionSet(input) {
+    const p = input.permissions ?? {};
+    const byPath = (a, b) => cmp(a.path, b.path);
+    return {
+        provides: sortedUnique(input.provides),
+        requires: sortedUnique(input.requires),
+        optional: sortedUnique(input.optional),
+        config: {
+            deployment: [...input.config.deployment].sort(byPath),
+            org: [...input.config.org].sort(byPath),
+        },
+        tables: sortedUnique(input.tables),
+        permissions: {
+            secrets: p.secrets === true,
+            storage: p.storage === true,
+            http: (p.http ?? [])
+                .map((r) => ({ method: r.method, path: r.path, public: r.public === true }))
+                .sort((a, b) => cmp(`${a.method} ${a.path}`, `${b.method} ${b.path}`)),
+            tools: sortedUnique(p.tools),
+            hooks: sortedUnique(p.hooks),
+            // only when declared: sets (and snapshots) of plugins without policy hooks stay as they were
+            ...(p.policyHooks && p.policyHooks.length > 0
+                ? { policyHooks: sortedUnique(p.policyHooks) }
+                : {}),
+            models: (p.models ?? [])
+                .map((m) => ({ purpose: m.purpose, kind: m.kind }))
+                .sort((a, b) => cmp(a.purpose, b.purpose)),
+            network: sortedUnique(p.network),
+            ui: { views: sortedUnique(p.ui?.views), embeds: sortedUnique(p.ui?.embeds) },
+        },
+        ...(input.warningsDigest ? { warningsDigest: input.warningsDigest } : {}),
+    };
+}
+/**
+ * 权限集合的稳定字符串键（排序），如 `provides:channel@1`、`config.org.secret:apiKey`、`table:todos`、
+ * `permissions.tools:write`、`permissions.http.public:POST /events`、`ui.view:tasks`、`ui.embed:board`。
+ * 容忍旧快照缺字段（按空处理），快照格式演进时不会抛错。
+ */
+export function permissionKeys(set) {
+    const s = (set ?? {});
+    const p = (s.permissions ?? {});
+    const keys = [];
+    for (const r of s.provides ?? [])
+        keys.push(`provides:${r}`);
+    for (const r of s.requires ?? [])
+        keys.push(`requires:${r}`);
+    for (const r of s.optional ?? [])
+        keys.push(`optional:${r}`);
+    for (const level of ["deployment", "org"]) {
+        for (const f of s.config?.[level] ?? []) {
+            keys.push(`config.${level}${f.secret ? ".secret" : ""}:${f.path || "<root>"}`);
+        }
+    }
+    for (const t of s.tables ?? [])
+        keys.push(`table:${t}`);
+    if (p.secrets)
+        keys.push("permissions.secrets");
+    if (p.storage)
+        keys.push("permissions.storage");
+    for (const r of p.http ?? []) {
+        keys.push(`permissions.http${r.public ? ".public" : ""}:${r.method} ${r.path}`);
+    }
+    for (const t of p.tools ?? [])
+        keys.push(`permissions.tools:${t}`);
+    for (const h of p.hooks ?? [])
+        keys.push(`permissions.hooks:${h}`);
+    for (const h of p.policyHooks ?? [])
+        keys.push(`${POLICY_HOOK_KEY_PREFIX}${h}`);
+    for (const m of p.models ?? [])
+        keys.push(`permissions.models:${m.purpose} (${m.kind})`);
+    for (const d of p.network ?? [])
+        keys.push(`permissions.network:${d}`);
+    for (const v of p.ui?.views ?? [])
+        keys.push(`${UI_VIEW_KEY_PREFIX}${v}`);
+    for (const e of p.ui?.embeds ?? [])
+        keys.push(`ui.embed:${e}`);
+    if (s.warningsDigest)
+        keys.push(`${WARNINGS_KEY_PREFIX}${s.warningsDigest}`);
+    return sortedUnique(keys);
+}
+/**
+ * Key prefix of a policy hook mount (manifest `permissions.policyHooks`): needs approval like any hook.
+ * Lower-case letters and dots only, as catalog permission keys require (`PERMISSION_KEY_RE`).
+ */
+export const POLICY_HOOK_KEY_PREFIX = "permissions.hooks.policy:";
+/** 渲染 schema 视图的权限键前缀：记入快照但不卡加载（见 {@link blockingKeys}）。 */
+export const UI_VIEW_KEY_PREFIX = "ui.view:";
+/**
+ * 新增项里需要批准（卡加载）的部分：除 `ui.view:*` 之外的全部。视图只是把插件已有的数据交给内核组件来画，
+ * 不给插件新能力（spec §4.1），升级多出视图时插件照常加载、快照自动补上。
+ */
+export function blockingKeys(added) {
+    return added.filter((k) => !k.startsWith(UI_VIEW_KEY_PREFIX));
+}
+/** 两份权限集合的差异（按 {@link permissionKeys}）；`prev` 为空（无快照）时全部算新增。 */
+export function diffPermissions(prev, next) {
+    const a = new Set(prev ? permissionKeys(prev) : []);
+    const b = new Set(permissionKeys(next));
+    return {
+        added: [...b].filter((k) => !a.has(k)),
+        removed: [...a].filter((k) => !b.has(k)),
+    };
+}