@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.6

package/dist/extensions/org-overrides.js

@@ -0,0 +1,524 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { isDeepStrictEqual } from "node:util";
+import { Inject, Injectable } from "@nestjs/common";
+import { configFields, getPath } from "../config/fields.js";
+import { createSecrets } from "../ctx/secrets.js";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { afterCommit } from "../infra/database/after-commit.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { KERNEL_LOGGER, KEYRING } from "../infra/tokens.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { toIssues } from "./config-issues.js";
+import { configMessages, safeConfigFormSchema } from "./config-json-schema.js";
+import { applySecretEntries } from "./deployment-config.js";
+import { deleteDeep, setDeep } from "./deployment-config-store.js";
+import { EffectiveConfigs, mergeCopy, OVERRIDE_SECRETS_NAMESPACE, overrideSecretKey, overrideSecretPaths, platformOverrideValues, } from "./effective-config.js";
+import { ExtensionHost } from "./host.js";
+import { extensionVisibleTo } from "./org-config.js";
+import { fieldLevels } from "./org-levels.js";
+const levelOf = (levels, path) => levels.get(path.split(".")[0]) ?? "hidden";
+const notOverridable = (plugin, paths) => new ApiError("extension.field_not_overridable", `These config fields of extension ${plugin} cannot be set by an organization: ${paths.join(", ")}`, paths.map((path) => ({ path })));
+const noCopy = (plugin) => new ApiError("extension.no_org_override", `This organization follows the platform configuration of extension ${plugin}`);
+/**
+ * Org copies of an extension's overridable deployment config (spec A §5.4, §5.5, §5.8): one row of
+ * `extension_org_overrides` per copy (its non-secret values), each secret in `capybara.secrets`
+ * under the org (namespace `kernel`, key `plugin-override:<plugin>:<path>`), written in the same
+ * transaction under the org row lock. Writes are org-audited and evict the cached copy after the
+ * commit. Platform secrets never enter a copy.
+ */
+let OrgOverrides = class OrgOverrides {
+    kdb;
+    txHost;
+    keyring;
+    host;
+    orgLock;
+    effective;
+    log;
+    constructor(kdb, txHost, keyring, host, 
+    /** The org row lock: re-checks `org.extensions.manage` under the lock. */
+    orgLock, effective, log) {
+        this.kdb = kdb;
+        this.txHost = txHost;
+        this.keyring = keyring;
+        this.host = host;
+        this.orgLock = orgLock;
+        this.effective = effective;
+        this.log = log;
+    }
+    get db() {
+        return this.kdb.db;
+    }
+    running(plugin) {
+        const inst = this.host.current(plugin);
+        if (!inst)
+            throw new ApiError("extension.not_found", `Extension ${plugin} is not installed`);
+        const schema = inst.manifest.config?.deployment;
+        return { inst, schema, levels: fieldLevels(schema) };
+    }
+    /**
+     * The running extension, for an org: one the org does not see under plugin scope (a `named`
+     * plugin without it) is answered like an unknown one, so its platform values never reach it.
+     */
+    async runningFor(orgId, plugin) {
+        const run = this.running(plugin);
+        if (!(await extensionVisibleTo(this.db, orgId, plugin))) {
+            throw new ApiError("extension.not_found", `Extension ${plugin} is not installed`);
+        }
+        return run;
+    }
+    /** The org's view (read-only and overridable fields, the copy state and validity). */
+    async view(orgId, plugin) {
+        return this.render(orgId, await this.runningFor(orgId, plugin));
+    }
+    /**
+     * Saves overridable fields (`values` keyed by field dot path: `null` clears, omitted keeps;
+     * secret fields too, as in the platform form) and secret record entries. The first save creates
+     * the copy from the platform's non-secret overridable values plus `values` (secret fields start
+     * empty). A path that is not an overridable field of the schema (read-only, hidden, unknown) ->
+     * 400 `extension.field_not_overridable`; an invalid result (an empty required secret included)
+     * -> 400 `extension.config_invalid`, nothing written. Audits `extension.org_override_saved`.
+     */
+    async save(orgId, plugin, values, secretEntries, actor) {
+        const run = await this.runningFor(orgId, plugin);
+        const fields = new Map((run.schema ? configFields(run.schema) : []).map((f) => [f.path, f.meta?.secret === true]));
+        const paths = [...Object.keys(values), ...secretEntries.map((e) => e.path)];
+        const refused = [
+            ...new Set(paths.filter((p) => !fields.has(p) || levelOf(run.levels, p) !== "override")),
+        ];
+        if (refused.length > 0)
+            throw notOverridable(plugin, refused);
+        const badEntries = secretEntries.filter((e) => fields.get(e.path) !== true || Object.hasOwn(values, e.path));
+        if (badEntries.length > 0) {
+            throw new ApiError("validation_failed", `Invalid secret entries for the organization config of extension ${plugin}`, badEntries.map((e) => ({
+                path: e.path,
+                message: Object.hasOwn(values, e.path)
+                    ? "given both in values and in secretEntries"
+                    : "not a secret field",
+            })));
+        }
+        return this.writeSave(orgId, plugin, run, fields, values, secretEntries, actor);
+    }
+    async writeSave(orgId, plugin, run, fields, values, secretEntries, actor) {
+        const schema = run.schema;
+        const t = this.db;
+        await this.orgLock.lockFor(orgId, actor.accountId, "org.extensions.manage");
+        const row = await this.lockedRow(orgId, plugin);
+        const platform = await this.host.rawDeploymentConfig(plugin);
+        const prior = row
+            ? { config: structuredClone(row.config), secrets: await this.readSecrets(orgId, plugin) }
+            : undefined;
+        const copy = prior
+            ? structuredClone(prior)
+            : { config: platformOverrideValues(schema, platform), secrets: {} };
+        for (const [path, v] of Object.entries(values)) {
+            if (fields.get(path)) {
+                if (v === null)
+                    delete copy.secrets[path];
+                else
+                    copy.secrets[path] = structuredClone(v);
+            }
+            else if (v === null)
+                deleteDeep(copy.config, path);
+            else
+                setDeep(copy.config, path, structuredClone(v));
+        }
+        if (secretEntries.length > 0) {
+            const records = {};
+            for (const e of secretEntries) {
+                if (copy.secrets[e.path] !== undefined) {
+                    setDeep(records, e.path, structuredClone(copy.secrets[e.path]));
+                }
+            }
+            applySecretEntries(records, secretEntries);
+            for (const e of secretEntries) {
+                const v = getPath(records, e.path);
+                if (v === undefined)
+                    delete copy.secrets[e.path];
+                else
+                    copy.secrets[e.path] = v;
+            }
+        }
+        const merged = this.validated(plugin, run, platform, copy);
+        // a secret is compared only with the copy's own previous value, never with the platform's
+        // (an audit that said "unchanged" would tell the org its key equals the platform's, A §5.5);
+        // on a first save every touched secret counts as changed
+        const before = prior ? mergeCopy(schema, platform, prior) : platform;
+        const changed = [...new Set(touchedPaths(values, secretEntries))]
+            .filter((p) => fields.get(p)
+            ? !prior || !isDeepStrictEqual(prior.secrets[p], copy.secrets[p])
+            : !isDeepStrictEqual(getPath(before, p), getPath(merged, p)))
+            .sort();
+        await t
+            .insertInto("extension_org_overrides")
+            .values({
+            plugin,
+            org_id: orgId,
+            config: JSON.stringify(copy.config),
+            created_by: actor.accountId,
+            updated_by: actor.accountId,
+        })
+            .onConflict((oc) => oc.columns(["plugin", "org_id"]).doUpdateSet({
+            config: JSON.stringify(copy.config),
+            updated_by: actor.accountId,
+            updated_at: new Date(),
+        }))
+            .execute();
+        await this.writeSecrets(orgId, plugin, schema, run.levels, copy.secrets);
+        await audit(t, {
+            actorAccountId: actor.accountId,
+            ...(actor.tokenId !== undefined && { actorTokenId: actor.tokenId }),
+            orgId,
+            action: "extension.org_override_saved",
+            target: plugin,
+            detail: { changedPaths: changed },
+        });
+        const secretValues = Object.values(copy.secrets);
+        afterCommit(async () => {
+            if (secretValues.length > 0)
+                this.log.addOrgSecrets(secretValues);
+            await this.effective.invalidate(orgId, plugin);
+        });
+        return this.render(orgId, run);
+    }
+    /**
+     * Takes the platform's current values of non-secret overridable fields into the copy (spec A
+     * §5.5); the copy stays a copy. A secret, read-only, hidden or unknown path -> 400
+     * `extension.field_not_overridable`; no copy -> 404 `extension.no_org_override`. Audits
+     * `extension.org_override_taken`.
+     */
+    async take(orgId, plugin, paths, actor) {
+        const run = await this.runningFor(orgId, plugin);
+        const fields = new Map((run.schema ? configFields(run.schema) : []).map((f) => [f.path, f.meta?.secret === true]));
+        const refused = [
+            ...new Set(paths.filter((p) => fields.get(p) !== false || levelOf(run.levels, p) !== "override")),
+        ];
+        if (refused.length > 0)
+            throw notOverridable(plugin, refused);
+        return this.writeTake(orgId, plugin, run, paths, actor);
+    }
+    async writeTake(orgId, plugin, run, paths, actor) {
+        const t = this.db;
+        await this.orgLock.lockFor(orgId, actor.accountId, "org.extensions.manage");
+        const row = await this.lockedRow(orgId, plugin);
+        if (!row)
+            throw noCopy(plugin);
+        const copy = {
+            config: structuredClone(row.config),
+            secrets: await this.readSecrets(orgId, plugin),
+        };
+        const platform = await this.host.rawDeploymentConfig(plugin);
+        const changed = [];
+        for (const p of [...new Set(paths)]) {
+            const v = getPath(platform, p);
+            if (!isDeepStrictEqual(getPath(copy.config, p), v))
+                changed.push(p);
+            if (v === undefined)
+                deleteDeep(copy.config, p);
+            else
+                setDeep(copy.config, p, structuredClone(v));
+        }
+        this.validated(plugin, run, platform, copy);
+        await t
+            .updateTable("extension_org_overrides")
+            .set({
+            config: JSON.stringify(copy.config),
+            updated_by: actor.accountId,
+            updated_at: new Date(),
+        })
+            .where("plugin", "=", plugin)
+            .where("org_id", "=", orgId)
+            .execute();
+        await audit(t, {
+            actorAccountId: actor.accountId,
+            ...(actor.tokenId !== undefined && { actorTokenId: actor.tokenId }),
+            orgId,
+            action: "extension.org_override_taken",
+            target: plugin,
+            detail: { changedPaths: changed.sort() },
+        });
+        afterCommit(() => this.effective.invalidate(orgId, plugin));
+        return this.render(orgId, run);
+    }
+    /**
+     * Drops the copy and every secret of it in one transaction; the org follows the platform again
+     * (spec A §5.5). No copy -> 404 `extension.no_org_override`. Audits `extension.org_override_reset`.
+     */
+    async reset(orgId, plugin, actor) {
+        return this.writeReset(orgId, plugin, await this.runningFor(orgId, plugin), actor);
+    }
+    async writeReset(orgId, plugin, run, actor) {
+        const t = this.db;
+        await this.orgLock.lockFor(orgId, actor.accountId, "org.extensions.manage");
+        const gone = await t
+            .deleteFrom("extension_org_overrides")
+            .where("plugin", "=", plugin)
+            .where("org_id", "=", orgId)
+            .returning("plugin")
+            .executeTakeFirst();
+        if (!gone)
+            throw noCopy(plugin);
+        const store = createSecrets(t, this.keyring, OVERRIDE_SECRETS_NAMESPACE);
+        for (const key of await this.secretKeys(orgId, plugin))
+            await store.delete(orgId, key);
+        await audit(t, {
+            actorAccountId: actor.accountId,
+            ...(actor.tokenId !== undefined && { actorTokenId: actor.tokenId }),
+            orgId,
+            action: "extension.org_override_reset",
+            target: plugin,
+        });
+        afterCommit(() => this.effective.invalidate(orgId, plugin));
+        return this.render(orgId, run);
+    }
+    /**
+     * The orgs (not deleted) holding a copy of the extension, oldest first, with the overridable
+     * non-secret fields that differ from the platform and whether each copy secret is set (spec A
+     * §5.7); never a secret value. Differences need the running schema: an extension not running on
+     * this replica lists no differences and only the secrets the copies hold.
+     */
+    async listForPlugin(plugin) {
+        const t = this.db;
+        const rows = await t
+            .selectFrom("extension_org_overrides as ov")
+            .innerJoin("orgs", "orgs.id", "ov.org_id")
+            .select(["ov.org_id", "orgs.name", "ov.created_at", "ov.config"])
+            .where("ov.plugin", "=", plugin)
+            .where("orgs.deleted_at", "is", null)
+            .orderBy("ov.created_at")
+            .orderBy("ov.org_id")
+            .execute();
+        const inst = this.host.current(plugin);
+        const schema = inst?.manifest.config?.deployment;
+        const levels = fieldLevels(schema);
+        const secretPaths = schema ? overrideSecretPaths(schema, levels) : undefined;
+        const plain = schema
+            ? configFields(schema).filter((f) => f.meta?.secret !== true && levelOf(levels, f.path) === "override")
+            : [];
+        const platform = rows.length > 0 ? await this.host.rawDeploymentConfig(plugin) : undefined;
+        const out = [];
+        for (const r of rows) {
+            const keys = await this.secretKeys(r.org_id, plugin);
+            const prefix = overrideSecretKey(plugin, "");
+            const held = new Set(keys.map((k) => k.slice(prefix.length)));
+            out.push({
+                orgId: r.org_id,
+                orgName: r.name,
+                createdAt: new Date(r.created_at).toISOString(),
+                differing: plain
+                    .filter((f) => {
+                    const own = getPath(r.config, f.path);
+                    return own !== undefined && !isDeepStrictEqual(own, getPath(platform, f.path));
+                })
+                    .map((f) => f.path),
+                secrets: (secretPaths ?? [...held].sort()).map((path) => ({ path, set: held.has(path) })),
+            });
+        }
+        return out;
+    }
+    /** The merged copy validated with the full schema; invalid -> 400 `extension.config_invalid`. */
+    validated(plugin, run, platform, copy) {
+        const schema = run.schema;
+        const merged = mergeCopy(schema, platform, copy);
+        const r = schema.safeParse(merged);
+        if (!r.success) {
+            throw new ApiError("extension.config_invalid", `Invalid organization copy of the configuration of extension ${plugin}`, orgIssues(toIssues(r.error, this.messagesOf(plugin, run)), run.levels));
+        }
+        return merged;
+    }
+    messagesOf(plugin, run) {
+        return configMessages(this.formSchemaOf(plugin, run));
+    }
+    /** The deployment form JSON Schema (hints dropped when invalid; one warning). Never throws. */
+    formSchemaOf(plugin, run) {
+        if (!run.schema)
+            return undefined;
+        const r = safeConfigFormSchema(run.schema, "deployment", (err, fallback) => this.log.warn("the deployment config form schema could not be built with its UI hints; hints dropped", { plugin, version: run.inst.manifest.version, schema: fallback, err }));
+        return r?.schema;
+    }
+    async lockedRow(orgId, plugin) {
+        return this.db
+            .selectFrom("extension_org_overrides")
+            .select(["config", "created_at"])
+            .where("plugin", "=", plugin)
+            .where("org_id", "=", orgId)
+            .forUpdate()
+            .executeTakeFirst();
+    }
+    /** The keys of the org's copy secrets for `plugin` (any path, current or stale). */
+    async secretKeys(orgId, plugin) {
+        const prefix = overrideSecretKey(plugin, "");
+        const rows = await this.db
+            .selectFrom("secrets")
+            .select("key")
+            .where("namespace", "=", OVERRIDE_SECRETS_NAMESPACE)
+            .where("org_id", "=", orgId)
+            .where("key", "like", `${prefix}%`)
+            .execute();
+        return rows.map((r) => r.key).filter((k) => k.startsWith(prefix));
+    }
+    async readSecrets(orgId, plugin) {
+        const prefix = overrideSecretKey(plugin, "");
+        const store = createSecrets(this.db, this.keyring, OVERRIDE_SECRETS_NAMESPACE);
+        const out = {};
+        for (const key of await this.secretKeys(orgId, plugin)) {
+            const v = await store.get(orgId, key);
+            if (v !== null)
+                out[key.slice(prefix.length)] = JSON.parse(v);
+        }
+        return out;
+    }
+    /** Writes the copy's secrets of the current schema and drops stale keys (paths no longer secret). */
+    async writeSecrets(orgId, plugin, schema, levels, secrets) {
+        const store = createSecrets(this.db, this.keyring, OVERRIDE_SECRETS_NAMESPACE);
+        const live = overrideSecretPaths(schema, levels);
+        for (const p of live) {
+            const v = secrets[p];
+            if (v === undefined)
+                await store.delete(orgId, overrideSecretKey(plugin, p));
+            else
+                await store.set(orgId, overrideSecretKey(plugin, p), JSON.stringify(v));
+        }
+        const keep = new Set(live.map((p) => overrideSecretKey(plugin, p)));
+        for (const key of await this.secretKeys(orgId, plugin)) {
+            if (!keep.has(key))
+                await store.delete(orgId, key);
+        }
+    }
+    async render(orgId, run) {
+        const row = await this.db
+            .selectFrom("extension_org_overrides")
+            .select(["config", "created_at"])
+            .where("plugin", "=", run.inst.name)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        const held = row ? new Set(await this.secretPathsHeld(orgId, run.inst.name)) : new Set();
+        // readonly values and secret state as the running instance has them (defaults applied, as
+        // the platform form shows); overridable values raw, as a copy stores and `take` copies them
+        const parsed = run.inst.config;
+        const raw = await this.host.rawDeploymentConfig(run.inst.name);
+        const fields = [];
+        for (const f of run.schema ? configFields(run.schema) : []) {
+            const level = levelOf(run.levels, f.path);
+            if (level === "hidden")
+                continue;
+            const secret = f.meta?.secret === true;
+            const pv = level === "override" && !secret
+                ? (getPath(raw, f.path) ?? getPath(parsed, f.path))
+                : getPath(parsed, f.path);
+            const field = {
+                path: f.path,
+                level,
+                secret,
+                platform: secret
+                    ? { set: pv !== undefined }
+                    : pv === undefined
+                        ? {}
+                        : { value: structuredClone(pv) },
+            };
+            if (row && level === "override") {
+                if (secret)
+                    field.org = { set: held.has(f.path) };
+                else {
+                    const ov = getPath(row.config, f.path);
+                    field.org = ov === undefined ? {} : { value: structuredClone(ov) };
+                    field.differs = ov !== undefined && !isDeepStrictEqual(ov, pv);
+                }
+            }
+            fields.push(field);
+        }
+        const eff = await this.effective.get(orgId, run.inst.name);
+        const form = this.formSchemaOf(run.inst.name, run);
+        return {
+            state: row ? "copy" : "following",
+            schema: form ? orgFormSchema(form, run.levels) : null,
+            ...(row && { createdAt: new Date(row.created_at).toISOString() }),
+            fields,
+            valid: eff.ok,
+            issues: eff.ok ? [] : orgIssues(eff.issues, run.levels),
+        };
+    }
+    async secretPathsHeld(orgId, plugin) {
+        const prefix = overrideSecretKey(plugin, "");
+        return (await this.secretKeys(orgId, plugin)).map((k) => k.slice(prefix.length));
+    }
+};
+__decorate([
+    Transactional()
+], OrgOverrides.prototype, "writeSave", null);
+__decorate([
+    Transactional()
+], OrgOverrides.prototype, "writeTake", null);
+__decorate([
+    Transactional()
+], OrgOverrides.prototype, "writeReset", null);
+__decorate([
+    Transactional({ isolationLevel: "repeatable read", accessMode: "read only" })
+], OrgOverrides.prototype, "listForPlugin", null);
+OrgOverrides = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(KEYRING)),
+    __param(3, Inject(ExtensionHost)),
+    __param(4, Inject(OrgLock)),
+    __param(5, Inject(EffectiveConfigs)),
+    __param(6, Inject(KERNEL_LOGGER))
+], OrgOverrides);
+export { OrgOverrides };
+/**
+ * The form JSON Schema an org may see (spec A §5.6, "hidden fields are not sent to the org at
+ * all"): a copy with only the read-only and overridable top-level properties, `required` limited
+ * to them, and root `x-ui` hints naming a hidden field dropped (`secrets[]` by path; `order` lists
+ * none). Values are never in it: `configJsonSchema` already strips secret defaults and examples.
+ */
+export function orgFormSchema(js, levels) {
+    const out = structuredClone(js);
+    const shown = (key) => (levels.get(key) ?? "hidden") !== "hidden";
+    const props = out.properties;
+    if (typeof props === "object" && props !== null) {
+        out.properties = Object.fromEntries(Object.entries(props).filter(([k]) => shown(k)));
+    }
+    if (Array.isArray(out.required)) {
+        out.required = out.required.filter((k) => typeof k === "string" && shown(k));
+    }
+    const ui = out["x-ui"];
+    if (typeof ui === "object" && ui !== null && !Array.isArray(ui)) {
+        const hints = ui;
+        if (Array.isArray(hints.secrets)) {
+            hints.secrets = hints.secrets.filter((e) => typeof e?.path === "string" && shown(e.path.split(".")[0]));
+        }
+    }
+    return out;
+}
+/** Every path a save touches. */
+function touchedPaths(values, entries) {
+    return [...Object.keys(values), ...entries.map((e) => e.path)];
+}
+/**
+ * Issues as an org may see them: an issue on a hidden field would name a field the org never
+ * sees, so those collapse into one root issue.
+ */
+export function orgIssues(issues, levels) {
+    const shown = issues.filter((i) => i.path !== "" && levelOf(levels, i.path) !== "hidden");
+    if (shown.length === issues.length)
+        return issues;
+    return [
+        ...shown,
+        {
+            path: "",
+            segments: [],
+            message: "the platform configuration of this extension is incomplete",
+        },
+    ];
+}

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

@@ -1,4 +1,5 @@
 import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+import type { PluginScope } from "../catalog/scope.js";
 import { type PermissionSet } from "./permission-set.js";
 import type { ExtensionSource } from "./sources.js";
 /**
@@ -36,10 +37,10 @@ export interface PermissionItem {
     reason?: SensitiveReason;
 }
 /**
- * 敏感的能力（D10 + 计划扩展，F-AI）：`sandbox@1` 在部署里执行任意命令、`object-store@1` 保管全部附件与插件包（D10）；
+ * 敏感的能力（D10 + 计划扩展，F-AI）：`sandbox@2` 在部署里执行任意命令、`object-store@1` 保管全部附件与插件包（D10）；
  * `channel@1` 收到组织在 IM 里的对话内容（Ruling A33）、`directory@1` 能把人加进组织（并为其建账号、建身份）、
  * `identity-source@1` 决定谁能登录成哪个账号。插件提供其中任何一个时，「提供」一组标为敏感，
- * 后台插件列表的 `sensitive` 为真，须企业管理员批准。只影响展示，不改权限快照的键。
+ * 后台插件列表的 `sensitive` 为真，须超级管理员批准。只影响展示，不改权限快照的键。
  */
 export declare const SENSITIVE_EXTENSION_POINTS: readonly string[];
 /**
@@ -59,7 +60,7 @@ export type DeploymentExtensionStatus = "enabled" | "disabled" | "pending_approv
 /** The stored package is in the pre-0.1.0 format: reinstall it from a repacked tgz. */
  | "legacy_format";
 /**
- * 需要企业管理员处理的状态（后台概览「需要处理的插件」）：待批准、待配置、失败、依赖缺失，以及副本不一致
+ * 需要超级管理员处理的状态（后台概览「需要处理的插件」）：待批准、待配置、失败、依赖缺失，以及副本不一致
  * （`converging` 收敛中、`pending_migration` 待迁移）。
  */
 export declare function extensionNeedsAction(status: DeploymentExtensionStatus): boolean;
@@ -114,13 +115,24 @@ export interface AdminExtensionView {
     /** 有部署级配置字段。 */
     configurable: boolean;
     configValid: boolean;
+    /**
+     * Only when the platform config leaves required overridable fields empty (spec A §5.4a; the
+     * extension still runs): the number of orgs where it is on and that still need their own config.
+     */
+    orgsNeedingConfig?: number;
     /** 能从部署卸载（只有安装记录，必需的引导插件除外；卸载前须先停用）。 */
     removable: boolean;
     /**
      * A required bootstrap plugin (package ecosystem spec §7): enabled in every org, cannot be
-     * disabled or uninstalled; an enterprise admin may upgrade it.
+     * disabled or uninstalled; a super admin may upgrade it.
      */
     required: boolean;
+    /** The scope of the catalog plugin the extension ships in (builtin: `all`); null without one. */
+    scope: PluginScope | null;
+    /** Orgs where the extension is enabled (a required plugin: every org). */
+    enabledOrgs: number;
+    /** Shipped with the deployment (a builtin plugin or a required bootstrap plugin). */
+    builtin: boolean;
     /** Where the install record came from (`bootstrap` for the bootstrap step); null for config-declared. */
     installSource: "npm" | "file" | "catalog" | "bootstrap" | null;
     /**

package/dist/extensions/permission-view.js

@@ -18,16 +18,16 @@ export function reviewHash(set, warnings = []) {
     return h.digest("hex").slice(0, 16);
 }
 /**
- * 敏感的能力（D10 + 计划扩展，F-AI）：`sandbox@1` 在部署里执行任意命令、`object-store@1` 保管全部附件与插件包（D10）；
+ * 敏感的能力（D10 + 计划扩展，F-AI）：`sandbox@2` 在部署里执行任意命令、`object-store@1` 保管全部附件与插件包（D10）；
  * `channel@1` 收到组织在 IM 里的对话内容（Ruling A33）、`directory@1` 能把人加进组织（并为其建账号、建身份）、
  * `identity-source@1` 决定谁能登录成哪个账号。插件提供其中任何一个时，「提供」一组标为敏感，
- * 后台插件列表的 `sensitive` 为真，须企业管理员批准。只影响展示，不改权限快照的键。
+ * 后台插件列表的 `sensitive` 为真，须超级管理员批准。只影响展示，不改权限快照的键。
  */
 export const SENSITIVE_EXTENSION_POINTS = [
     "channel@1",
     "directory@1",
     "identity-source@1",
-    "sandbox@1",
+    "sandbox@2",
     "object-store@1",
 ];
 /** 总是敏感的类别。 */
@@ -159,7 +159,7 @@ export function permissionGroups(set) {
     });
 }
 /**
- * 需要企业管理员处理的状态（后台概览「需要处理的插件」）：待批准、待配置、失败、依赖缺失，以及副本不一致
+ * 需要超级管理员处理的状态（后台概览「需要处理的插件」）：待批准、待配置、失败、依赖缺失，以及副本不一致
  * （`converging` 收敛中、`pending_migration` 待迁移）。
  */
 export function extensionNeedsAction(status) {

package/dist/extensions/plugin-items.d.ts

@@ -0,0 +1,21 @@
+import type { PluginScope } from "../catalog/scope.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+/** The catalog item (the plugin) an extension ships in. */
+export interface ExtensionPluginItem {
+    id: string;
+    scope: PluginScope;
+    builtin: boolean;
+    disabled: boolean;
+}
+/**
+ * The live catalog items of each extension in `names`, the one recorded on its install
+ * (`extension_installs.catalog_item_id`) first, then its other `extension_catalog_sources` by id.
+ * An extension without a live item (declared in the startup config, or its items deleted) is absent.
+ * `db` may be a transaction.
+ */
+export declare function pluginItemsOf(db: KernelSchemaDb, names: readonly string[]): Promise<Map<string, ExtensionPluginItem[]>>;
+/**
+ * Whether an item keeps its plugin on in every org (builtin only: an org may switch off an `all`
+ * one, layering spec §4): its switch cannot go off.
+ */
+export declare const itemLocked: (i: ExtensionPluginItem) => boolean;

package/dist/extensions/plugin-items.js

@@ -0,0 +1,42 @@
+/**
+ * The live catalog items of each extension in `names`, the one recorded on its install
+ * (`extension_installs.catalog_item_id`) first, then its other `extension_catalog_sources` by id.
+ * An extension without a live item (declared in the startup config, or its items deleted) is absent.
+ * `db` may be a transaction.
+ */
+export async function pluginItemsOf(db, names) {
+    const out = new Map();
+    if (names.length === 0)
+        return out;
+    const add = (plugin, item) => {
+        const list = out.get(plugin) ?? [];
+        if (!list.some((i) => i.id === item.id))
+            list.push(item);
+        out.set(plugin, list);
+    };
+    const own = await db
+        .selectFrom("extension_installs as e")
+        .innerJoin("catalog_items as i", "i.id", "e.catalog_item_id")
+        .select(["e.name as plugin", "i.id", "i.scope", "i.builtin", "i.disabled"])
+        .where("e.name", "in", [...names])
+        .where("i.deleted_at", "is", null)
+        .execute();
+    for (const r of own)
+        add(r.plugin, r);
+    const sources = await db
+        .selectFrom("extension_catalog_sources as s")
+        .innerJoin("catalog_items as i", "i.id", "s.item_id")
+        .select(["s.plugin", "i.id", "i.scope", "i.builtin", "i.disabled"])
+        .where("s.plugin", "in", [...names])
+        .where("i.deleted_at", "is", null)
+        .orderBy("i.id")
+        .execute();
+    for (const r of sources)
+        add(r.plugin, r);
+    return out;
+}
+/**
+ * Whether an item keeps its plugin on in every org (builtin only: an org may switch off an `all`
+ * one, layering spec §4): its switch cannot go off.
+ */
+export const itemLocked = (i) => i.builtin;