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

package/dist/catalog/org-catalog.service.js

@@ -0,0 +1,625 @@
+import { createHash } from "node:crypto";
+import { parseAgentTemplate, parseConnectorTemplateFile, } from "@capybara-hq/plugin-sdk";
+import { ApiError } from "../errors.js";
+import { lockOrgAndAuthorize } from "../orgs/org-lock.js";
+import { can, roleAtLeast } from "../orgs/roles.js";
+import { packagePath } from "../packages/tgz.js";
+import { checkSkillFiles, SkillArchiveError } from "../skills/package.js";
+import { itemView } from "./catalog.service.js";
+import { iconProblem } from "./plugin-package.js";
+import { upgradeInfo } from "./upgrade-targets.js";
+import { satisfiesRange } from "./versions.js";
+/**
+ * A connector template as an org sees it (the install wizard and the upgrade preview's inputs):
+ * presets and editable paths, no credentials.
+ */
+export function orgTemplateView(id, file) {
+    const t = file.template;
+    return {
+        id,
+        displayName: file.displayName,
+        description: file.description ?? "",
+        plugin: t.plugin,
+        connector: t.connector,
+        endpoint: t.endpoint,
+        editableEndpoint: t.editableEndpoint ?? [],
+        auth: t.auth,
+        ownership: t.ownership ??
+            (typeof t.auth.ownership === "string" ? t.auth.ownership : null),
+    };
+}
+const iconNotFound = () => new ApiError("catalog.icon_not_found", "This catalog item has no icon");
+/**
+ * The item's latest version row; item missing, deleted or (when `includeDisabled` is false)
+ * disabled -> `catalog.item_not_found`.
+ */
+async function latestVersionRow(db, itemId, includeDisabled) {
+    if (!UUID_RE.test(itemId))
+        throw itemNotFound();
+    const item = await db
+        .selectFrom("catalog_items")
+        .select(["latest_version", "policy"])
+        .where("id", "=", itemId)
+        .where("deleted_at", "is", null)
+        .executeTakeFirst();
+    // An item the caller cannot see is "not found" before any version / storage is read, so "no icon"
+    // never reveals that it exists
+    if (!item || (!includeDisabled && item.policy === "disabled"))
+        throw itemNotFound();
+    const v = await db
+        .selectFrom("catalog_item_versions")
+        .select(["manifest", "object_prefix", "files"])
+        .where("item_id", "=", itemId)
+        .where("version", "=", item.latest_version)
+        .executeTakeFirst();
+    if (!v)
+        throw itemNotFound();
+    return { item, v };
+}
+/** The icon's path in the version's files (undefined without an icon). */
+const iconPath = (v) => {
+    const icon = v.manifest.icon;
+    return icon === undefined ? undefined : packagePath(icon);
+};
+/** Whether the item's latest version has an icon; unreadable counts as none. */
+export async function catalogHasIcon(db, itemId) {
+    try {
+        const { v } = await latestVersionRow(db, itemId, true);
+        const path = iconPath(v);
+        return path !== undefined && v.files.some((f) => f.path === path);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Reads the icon of the item's latest version (served only through kernel routes, with nosniff and
+ * a CSP sandbox in the response headers; the web only shows it with `<img>`). Item missing, deleted
+ * or (when `includeDisabled` is false) disabled -> `catalog.item_not_found` (decided before reading
+ * storage); no icon -> `catalog.icon_not_found`; stored content that is not a valid svg / png
+ * (checked at import, this guards against tampered storage) -> `internal`.
+ */
+export async function readCatalogIcon(db, storage, itemId, includeDisabled) {
+    const { item, v } = await latestVersionRow(db, itemId, includeDisabled);
+    const path = iconPath(v);
+    const f = path === undefined ? undefined : v.files.find((x) => x.path === path);
+    if (path === undefined || !f)
+        throw iconNotFound();
+    const [file] = await readCatalogFiles(storage, v.object_prefix, [f]);
+    if (!file)
+        throw iconNotFound();
+    const problem = iconProblem(path, file.data);
+    if (problem !== undefined)
+        throw new ApiError("internal", `Stored icon is invalid: ${problem}`);
+    return {
+        data: file.data,
+        contentType: /\.svg$/i.test(path) ? "image/svg+xml" : "image/png",
+        policy: item.policy,
+    };
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const itemNotFound = () => new ApiError("catalog.item_not_found", "Catalog item not found");
+const itemDisabled = () => new ApiError("catalog.item_disabled", "This catalog item is disabled by the enterprise admin and cannot be newly installed");
+const fail = (path, message) => new ApiError("validation_failed", "Request validation failed", [{ path, message }]);
+/**
+ * The org actions installing / uninstalling a plugin needs: the union over its components (an
+ * extension -> `org.extensions.manage`, skills -> `skills.manage`, connector templates ->
+ * `connectors.manage`, agent templates -> `agents.manage`), re-checked inside the org row lock.
+ */
+export function requiredActions(m) {
+    const out = [];
+    if (m.extension)
+        out.push("org.extensions.manage");
+    if ((m.connectorTemplates ?? []).length > 0)
+        out.push("connectors.manage");
+    if ((m.skills ?? []).length > 0)
+        out.push("skills.manage");
+    if ((m.agents ?? []).length > 0)
+        out.push("agents.manage");
+    return out.length > 0 ? out : ["org.extensions.manage"];
+}
+/** Locks the org row in the caller's transaction and re-checks the actor can do every action (else `forbidden`). */
+export async function lockOrgForActions(t, orgId, actor, actions) {
+    const [first, ...rest] = actions;
+    const { role } = await lockOrgAndAuthorize(t, orgId, actor, first);
+    for (const a of rest) {
+        if (!can(role, a))
+            throw new ApiError("forbidden", "Insufficient organization role");
+    }
+}
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const UNSAFE_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+/** 对象的全部叶子点路径（数组与非对象值算叶子）。 */
+function leafPaths(v, base = "") {
+    const out = [];
+    for (const [k, x] of Object.entries(v)) {
+        const p = base ? `${base}.${k}` : k;
+        if (isObj(x) && Object.keys(x).length > 0)
+            out.push(...leafPaths(x, p));
+        else
+            out.push(p);
+    }
+    return out;
+}
+/** The value at a dot path of `v` (own keys only), undefined when absent. */
+export function getPath(v, path) {
+    let node = v;
+    for (const seg of path.split(".")) {
+        if (!isObj(node) || !Object.hasOwn(node, seg))
+            return undefined;
+        node = node[seg];
+    }
+    return node;
+}
+/** Sets the value at a dot path of `obj`, creating the objects on the way. */
+export function setPath(obj, path, value) {
+    const segs = path.split(".");
+    let node = obj;
+    for (const seg of segs.slice(0, -1)) {
+        if (!isObj(node[seg]))
+            node[seg] = {};
+        node = node[seg];
+    }
+    node[segs[segs.length - 1]] = value;
+}
+/**
+ * 模板的连接器插件此刻是否可用：插件加载且提供该 kind，并满足 `pluginVersion`（若写了）；不可用返回原因
+ * （模型不可见，给管理员看的英文）。
+ */
+export function templatePluginProblem(d, template) {
+    if (!d.findConnector(template.plugin, template.connector)) {
+        return `Connector extension ${template.plugin} providing "${template.connector}" is not deployed; ask the enterprise admin to install and enable it`;
+    }
+    const range = template.pluginVersion;
+    const version = d.pluginVersion(template.plugin);
+    if (range !== undefined && version !== undefined && !satisfiesRange(version, range)) {
+        return `Connector extension ${template.plugin} is deployed at version ${version}, but the template needs ${range}; ask the enterprise admin to upgrade it`;
+    }
+    return undefined;
+}
+/**
+ * Builds the connector install input from a connector template plus what the org filled in (C30):
+ * the endpoint comes from the template, only paths listed in `editableEndpoint` (or fields under
+ * them) may be changed by the org, changing another path -> `validation_failed`; the auth method
+ * comes from the template, the org only gives credentials (static credentials via `credential`,
+ * OAuth via `client`). Re-checks the template's plugin, kind and `pluginVersion` against the
+ * connectors loaded on this replica right now (unmet -> `catalog.not_deployed`); the endpoint
+ * (merged as a whole) schema check, credential pattern check and OAuth URL policy are re-checked by
+ * `ConnectorsService.create`.
+ */
+export function templateConnectorInput(deps, template, ref, input, defaultName, at = "connector") {
+    const problem = templatePluginProblem(deps, template);
+    if (problem !== undefined)
+        throw new ApiError("catalog.not_deployed", problem);
+    const given = input ?? {};
+    const editable = template.editableEndpoint ?? [];
+    const endpoint = structuredClone(template.endpoint);
+    if (given.endpoint !== undefined) {
+        if (!isObj(given.endpoint))
+            throw fail(`${at}.endpoint`, "Expected an object");
+        for (const p of leafPaths(given.endpoint)) {
+            const segs = p.split(".");
+            if (segs.some((s) => UNSAFE_KEYS.has(s))) {
+                throw fail(`${at}.endpoint.${p}`, "Invalid key");
+            }
+            const allowed = editable.some((e) => p === e || p.startsWith(`${e}.`));
+            if (!allowed) {
+                throw fail(`${at}.endpoint.${p}`, "This endpoint field is set by the template and cannot be changed");
+            }
+        }
+        for (const e of editable) {
+            const v = getPath(given.endpoint, e);
+            if (v !== undefined)
+                setPath(endpoint, e, v);
+        }
+    }
+    const auth = template.auth;
+    const oauth = auth.type === "oauth_code" || auth.type === "oauth_client";
+    if (oauth && given.credential !== undefined) {
+        throw fail(`${at}.credential`, "This connector uses OAuth; provide client instead");
+    }
+    if (!oauth && given.client !== undefined) {
+        throw fail(`${at}.client`, "This connector does not use OAuth; provide credential instead");
+    }
+    const credential = oauth ? given.client : given.credential;
+    return {
+        name: given.name ?? defaultName,
+        ...(given.slug !== undefined && { slug: given.slug }),
+        connector: template.connector,
+        endpoint,
+        auth,
+        ...(credential !== undefined && { credential }),
+        template: {
+            ...ref,
+            ...(template.defaultToolPolicies !== undefined && {
+                defaultToolPolicies: template.defaultToolPolicies,
+            }),
+        },
+    };
+}
+/** 从部署存储读目录版本里的文件（按版本行的 sha256 校验）；`under` 给出时只读该目录下的文件，路径去掉该前缀。 */
+export async function readCatalogFiles(storage, objectPrefix, files, under) {
+    storage.assertAvailable();
+    if (objectPrefix === null)
+        return [];
+    const store = storage.deployment();
+    const dir = under === undefined ? "" : `${under}/`;
+    const out = [];
+    for (const f of files) {
+        if (!f.path.startsWith(dir))
+            continue;
+        const got = await store.get(`${objectPrefix}${f.path}`);
+        if (!got) {
+            throw new ApiError("storage.unavailable", `Catalog file ${f.path} is missing from object storage`);
+        }
+        const data = new Uint8Array(await new Response(got.body).arrayBuffer());
+        if (createHash("sha256").update(data).digest("hex") !== f.sha256) {
+            throw new ApiError("internal", `Catalog file ${f.path} does not match its recorded hash`);
+        }
+        out.push({ path: f.path.slice(dir.length), size: data.byteLength, sha256: f.sha256, data });
+    }
+    return out;
+}
+/** 校验技能文件并取名字与描述（导入时已校验过；这里防存储被改）。 */
+export function skillOf(files) {
+    try {
+        // Stored files: a version imported before phase D keeps installing (its invocation keys are
+        // read leniently; `skillInvocation` ignores values of the wrong type)
+        return checkSkillFiles(files, { invocationKeys: false });
+    }
+    catch (e) {
+        if (e instanceof SkillArchiveError) {
+            throw new ApiError("internal", `Stored skill is invalid: ${e.problems.join("; ")}`);
+        }
+        throw e;
+    }
+}
+/** The connector templates of a catalog version, read from storage (id = the file's base name). */
+export async function readCatalogTemplates(storage, v) {
+    const refs = v.manifest.connectorTemplates ?? [];
+    if (refs.length === 0)
+        return [];
+    const paths = refs.map((r) => packagePath(r.path));
+    const files = await readCatalogFiles(storage, v.object_prefix, v.files.filter((f) => paths.includes(f.path)));
+    return paths.map((path) => {
+        const f = files.find((x) => x.path === path);
+        let parsed;
+        try {
+            parsed = f && parseConnectorTemplateFile(JSON.parse(new TextDecoder().decode(f.data)));
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (!parsed || "errors" in parsed) {
+            throw new ApiError("internal", `Stored connector template ${path} is missing or invalid`);
+        }
+        return { id: path.split("/").pop().replace(/\.json$/, ""), file: parsed };
+    });
+}
+/**
+ * The agent templates of a catalog version (`manifest.agents`, listed explicitly since import),
+ * parsed from storage (checked at import; parsed again in case storage was changed).
+ */
+export async function readCatalogAgentTemplates(storage, v) {
+    const refs = v.manifest.agents ?? [];
+    if (refs.length === 0)
+        return [];
+    const paths = refs.map((r) => packagePath(r.path));
+    const files = await readCatalogFiles(storage, v.object_prefix, v.files.filter((f) => paths.includes(f.path)));
+    return paths.map((path) => {
+        const f = files.find((x) => x.path === path);
+        const parsed = f && parseAgentTemplate(new TextDecoder().decode(f.data));
+        if (!parsed || "errors" in parsed) {
+            throw new ApiError("internal", `Stored agent template ${path} is missing or invalid`);
+        }
+        return { path, template: parsed.template };
+    });
+}
+/**
+ * Organizations browse and install from the enterprise catalog (C22): members browse (without
+ * disabled items) and request, org admins install. Every item is a plugin, installed with its
+ * dependencies by {@link PluginInstaller}; installing requires the union of the component actions
+ * of the plugins it brings in ({@link requiredActions}), re-checked inside the org row lock; item
+ * disabled -> `catalog.item_disabled`; a dependency unresolved / disabled / in a cycle ->
+ * `catalog.dependency_*`; an extension or a template's connector not on the deployment ->
+ * `catalog.not_deployed`; needs_approval without a grant -> a stage deployment request (HTTP 202;
+ * dependencies are not approved separately, spec §10). No in-process state.
+ */
+export class OrgCatalogService {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    /** The org's view of the items; members (not admins) don't see disabled items. */
+    async list(orgId, accountId, itemId) {
+        const m = await this.d.db
+            .selectFrom("memberships")
+            .select("role")
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .executeTakeFirst();
+        const isAdmin = m !== undefined && roleAtLeast(m.role, "admin");
+        let q = this.d.db
+            .selectFrom("catalog_items")
+            .selectAll()
+            .where("deleted_at", "is", null)
+            .orderBy("name")
+            .orderBy("id");
+        if (itemId !== undefined)
+            q = q.where("id", "=", itemId);
+        if (!isAdmin)
+            q = q.where("policy", "<>", "disabled");
+        const items = await q.execute();
+        if (items.length === 0)
+            return [];
+        const ids = items.map((i) => i.id);
+        const [versions, grants, requests, pluginInstalls] = await Promise.all([
+            this.d.db
+                .selectFrom("catalog_item_versions")
+                .select(["item_id", "version", "source", "manifest", "object_prefix", "files"])
+                .where("item_id", "in", ids)
+                .execute(),
+            this.d.db
+                .selectFrom("catalog_org_grants")
+                .select("item_id")
+                .where("org_id", "=", orgId)
+                .execute(),
+            this.d.requests.latestByItem(orgId),
+            this.d.db
+                .selectFrom("plugin_installs")
+                .select(["id", "item_id", "version"])
+                .where("org_id", "=", orgId)
+                .where("status", "in", ["installing", "installed", "upgrading"])
+                .execute(),
+        ]);
+        const upgrades = await upgradeInfo(this.d.db, this.d.host, pluginInstalls.flatMap((a) => {
+            const item = items.find((i) => i.id === a.item_id);
+            return item ? [{ itemId: a.item_id, name: item.name, version: a.version }] : [];
+        }));
+        const granted = new Set(grants.map((g) => g.item_id));
+        const undeployed = await this.undeployed(items.flatMap((i) => {
+            const v = versions.find((x) => x.item_id === i.id && x.version === i.latest_version);
+            return v ? [v] : [];
+        }));
+        const out = [];
+        for (const i of items) {
+            const vs = versions.filter((v) => v.item_id === i.id);
+            const { installs: _installs, marketplaceId: _source, latestMarketplaceVersion: _latest, newerInMarketplace: _newer, ...view } = itemView(i, vs);
+            const latest = vs.find((v) => v.version === i.latest_version);
+            let installable;
+            if (i.policy === "disabled")
+                installable = "disabled";
+            else if (latest && undeployed.has(i.id)) {
+                installable = "not_deployed";
+            }
+            else if (i.policy === "needs_approval") {
+                installable = granted.has(i.id) ? "granted" : "needs_approval";
+            }
+            else
+                installable = "yes";
+            const a = pluginInstalls.find((x) => x.item_id === i.id);
+            out.push({
+                ...view,
+                installable,
+                installed: a
+                    ? {
+                        pluginInstallId: a.id,
+                        version: a.version,
+                        upgradeAvailable: upgrades.get(`${a.item_id}@${a.version}`)?.upgradeAvailable ?? null,
+                    }
+                    : null,
+                request: requests.get(i.id) ?? null,
+            });
+        }
+        return out;
+    }
+    /**
+     * Item detail (for the install wizard): the same view as the list (members don't see disabled
+     * items, not visible means `catalog.item_not_found`), plus the latest version's extension,
+     * connector templates (endpoint preset, editable paths, auth preset), dependencies, skills and
+     * agent templates.
+     */
+    async detail(orgId, accountId, itemId) {
+        if (!UUID_RE.test(itemId))
+            throw itemNotFound();
+        const [item] = await this.list(orgId, accountId, itemId);
+        if (!item)
+            throw itemNotFound();
+        const v = await this.d.db
+            .selectFrom("catalog_item_versions")
+            .select(["manifest", "object_prefix", "files"])
+            .where("item_id", "=", itemId)
+            .where("version", "=", item.latestVersion)
+            .executeTakeFirst();
+        if (!v)
+            throw itemNotFound();
+        const m = v.manifest;
+        return {
+            item,
+            hasIcon: m.icon !== undefined,
+            extension: m.extension ? m.name : null,
+            templates: (await readCatalogTemplates(this.d.storage, v)).map((t) => orgTemplateView(t.id, t.file)),
+            dependencies: (m.dependencies ?? []).map((d) => ({ name: d.name, range: d.version })),
+            skills: (m.skills ?? []).map((s) => packagePath(s.path)),
+            agents: (m.agents ?? []).map((a) => packagePath(a.path)),
+        };
+    }
+    /**
+     * The item's icon; members don't see disabled items (-> `catalog.item_not_found`, decided before
+     * reading storage).
+     */
+    icon(itemId, isAdmin) {
+        return readCatalogIcon(this.d.db, this.d.storage, itemId, isAdmin);
+    }
+    /** For the admin item detail: whether the latest version has an icon. */
+    hasIcon(itemId) {
+        return catalogHasIcon(this.d.db, itemId);
+    }
+    /**
+     * The items (latest versions) this replica cannot install now: the plugin's extension is not
+     * loaded, or a connector template's connector extension is not (or not at the template's
+     * `pluginVersion`). Dependencies are judged at install. A template that cannot be read counts as
+     * deployed here (the install reads it again).
+     */
+    async undeployed(versions) {
+        const loaded = new Map(this.d.host.manifests().map((m) => [m.name, m.version]));
+        const deps = {
+            findConnector: this.d.findConnector,
+            pluginVersion: (n) => loaded.get(n),
+        };
+        const out = new Set();
+        await Promise.all(versions.map(async (v) => {
+            const m = v.manifest;
+            if (m.extension && !loaded.has(m.name)) {
+                out.add(v.item_id);
+                return;
+            }
+            if ((m.connectorTemplates ?? []).length === 0)
+                return;
+            try {
+                const templates = await readCatalogTemplates(this.d.storage, v);
+                if (templates.some((t) => templatePluginProblem(deps, t.file.template) !== undefined)) {
+                    out.add(v.item_id);
+                }
+            }
+            catch (e) {
+                // Unreadable here: counted as deployed, the install reports it
+                this.d.log?.warn("catalog template read failed in the org list", {
+                    itemId: v.item_id,
+                    error: e instanceof Error ? e.message : String(e),
+                });
+            }
+        }));
+        return out;
+    }
+    /** Installs a plugin in the org (see the class comment). */
+    async install(orgId, actor, itemId, body, actorTokenId) {
+        if (!UUID_RE.test(itemId))
+            throw itemNotFound();
+        // The role first (forbidden when it can install nothing), then item errors: a member cannot
+        // probe the existence or versions of a disabled item through error codes
+        await this.d.db.transaction().execute(async (t) => {
+            const { role } = await lockOrgAndAuthorize(t, orgId, actor, "catalog.read");
+            const canAny = ["org.extensions.manage", "connectors.manage", "skills.manage"].some((a) => can(role, a));
+            if (!canAny)
+                throw new ApiError("forbidden", "Insufficient organization role");
+        });
+        const item = await this.d.db
+            .selectFrom("catalog_items")
+            .selectAll()
+            .where("id", "=", itemId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!item)
+            throw itemNotFound();
+        const version = body.version ?? item.latest_version;
+        const v = await this.d.db
+            .selectFrom("catalog_item_versions")
+            .select("version")
+            .where("item_id", "=", itemId)
+            .where("version", "=", version)
+            .executeTakeFirst();
+        if (!v)
+            throw new ApiError("catalog.item_not_found", `Version ${version} of this item not found`);
+        const opts = actorTokenId !== undefined ? { actorTokenId } : {};
+        if (item.policy === "disabled")
+            throw itemDisabled();
+        // Dependencies resolved, extensions deployed, template connectors available: before a request
+        // is created. The actions are the union over the plugins the install brings in
+        const { actions } = await this.d.pluginInstaller.preflight(orgId, actor, itemId, version);
+        // 1. Role and policy under the lock; needs_approval without a grant -> a request (202). Approval
+        //    follows this plugin's policy only, not its dependencies' (spec §10)
+        const pending = await this.d.db.transaction().execute(async (t) => {
+            await lockOrgForActions(t, orgId, actor, actions);
+            const locked = await t
+                .selectFrom("catalog_items")
+                .select(["policy", "deleted_at"])
+                .where("id", "=", itemId)
+                .forShare()
+                .executeTakeFirst();
+            if (!locked || locked.deleted_at !== null)
+                throw itemNotFound();
+            if (locked.policy === "disabled")
+                throw itemDisabled();
+            if (locked.policy === "needs_approval") {
+                const grant = await t
+                    .selectFrom("catalog_org_grants")
+                    .select("item_id")
+                    .where("item_id", "=", itemId)
+                    .where("org_id", "=", orgId)
+                    .executeTakeFirst();
+                if (!grant) {
+                    return this.d.requests.requestDeployment(t, orgId, actor, item, version, opts);
+                }
+            }
+            return undefined;
+        });
+        if (pending !== undefined) {
+            return { status: 202, request: await this.d.requests.view(this.d.db, pending) };
+        }
+        // 2. Install (each step re-checks the item policy in its own transaction)
+        const { version: _version, ...input } = body;
+        const view = await this.d.pluginInstaller.install(orgId, actor, itemId, version, input, opts);
+        return {
+            status: 201,
+            installed: { itemId, version, pluginInstallId: view.id },
+            install: view,
+        };
+    }
+    /** The upgrade preview of an org install (spec §10, see `PluginUpgrader`). */
+    async upgradePreview(orgId, actor, installId, version) {
+        await this.assertCanInstall(orgId, actor);
+        return this.d.pluginUpgrader.preview(orgId, actor, installId, version);
+    }
+    /**
+     * Upgrades an org install in place (spec §10, Decision 11): the preview's `diffHash` is checked
+     * first (`plugin.upgrade_stale`); the item disabled -> `catalog.item_disabled`; needs_approval
+     * without a grant -> a stage deployment request for the target version (202; after approval the
+     * org admin runs the upgrade again); otherwise the upgrade runs (200, the install view).
+     */
+    async upgrade(orgId, actor, installId, body, actorTokenId) {
+        await this.assertCanInstall(orgId, actor);
+        const opts = actorTokenId !== undefined ? { actorTokenId } : {};
+        const { itemId, actions, diff } = await this.d.pluginUpgrader.check(orgId, actor, installId, body);
+        const pending = await this.d.db.transaction().execute(async (t) => {
+            await lockOrgForActions(t, orgId, actor, actions);
+            const locked = await t
+                .selectFrom("catalog_items")
+                .select(["id", "name", "policy", "deleted_at"])
+                .where("id", "=", itemId)
+                .forShare()
+                .executeTakeFirst();
+            if (!locked || locked.deleted_at !== null)
+                throw itemNotFound();
+            if (locked.policy === "disabled")
+                throw itemDisabled();
+            if (locked.policy !== "needs_approval")
+                return undefined;
+            const grant = await t
+                .selectFrom("catalog_org_grants")
+                .select("item_id")
+                .where("item_id", "=", itemId)
+                .where("org_id", "=", orgId)
+                .executeTakeFirst();
+            if (grant)
+                return undefined;
+            return this.d.requests.requestDeployment(t, orgId, actor, locked, body.version, opts);
+        });
+        if (pending !== undefined) {
+            return { status: 202, request: await this.d.requests.view(this.d.db, pending) };
+        }
+        return {
+            status: 200,
+            install: await this.d.pluginUpgrader.upgrade(orgId, actor, installId, body, opts, diff),
+        };
+    }
+    /** The actor can install something in the org (forbidden otherwise), checked before item errors. */
+    async assertCanInstall(orgId, actor) {
+        await this.d.db.transaction().execute(async (t) => {
+            const { role } = await lockOrgAndAuthorize(t, orgId, actor, "catalog.read");
+            const canAny = ["org.extensions.manage", "connectors.manage", "skills.manage"].some((a) => can(role, a));
+            if (!canAny)
+                throw new ApiError("forbidden", "Insufficient organization role");
+        });
+    }
+}