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

package/dist/extensions/installs.js

@@ -0,0 +1,253 @@
+import { SDK_VERSION } from "@capybara-hq/plugin-sdk";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { lockEnterpriseAdminsAndAuthorize } from "../identity/enterprise-admin.js";
+import { fetchNpmPackage, IntegrityMismatchError, NpmFetchError, PackageTooLargeError, } from "../packages/npm.js";
+import { fetchProvenance, PROVENANCE_TIMEOUT_MS, } from "../packages/provenance.js";
+import { ExtensionApprovals } from "./approvals.js";
+import { ExtensionPackageError, extensionPackageApiError, permissionSetOfPackage, readExtensionPackage, } from "./package.js";
+import { diffPermissions } from "./permission-set.js";
+import { migrationWarnings, permissionGroups, permissionKeyItems, reviewHash, } from "./permission-view.js";
+export { migrationWarnings };
+/** 插件安装记录与包的导入（上传文件、npm）。本身无状态，多副本共用。 */
+export class ExtensionInstalls {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    /**
+     * Validates and stores one package and returns the review; audits `extension.package_uploaded`.
+     * Only stores: no install, no desired state change (T14).
+     * - Over `packages.maxBytes` -> `extension.package_too_large`; invalid package ->
+     *   `extension.package_invalid` (details list each problem);
+     * - extension name equal to a config-declared one -> `extension.config_declared`;
+     * - an install record of the same name comes from another npm package -> `extension.name_conflict`
+     *   (a new version of the same package is an upgrade, handled elsewhere).
+     * `actor` null means the CLI (no enterprise admin re-check, audit without an actor).
+     */
+    async ingest(actor, bytes, src, opts = {}) {
+        const maxBytes = this.d.config().packages.maxBytes;
+        if (bytes.byteLength > maxBytes) {
+            throw new ApiError("extension.package_too_large", `The extension package is larger than ${maxBytes} bytes`);
+        }
+        let pkg;
+        try {
+            pkg = await readExtensionPackage(bytes, { maxBytes, hostSdkVersion: SDK_VERSION });
+        }
+        catch (e) {
+            if (e instanceof ExtensionPackageError)
+                throw extensionPackageApiError(e);
+            throw e;
+        }
+        const m = pkg.section.manifest;
+        const packageName = String(pkg.packageJson.name);
+        if (opts.expectPackageName !== undefined && packageName !== opts.expectPackageName) {
+            const issue = `package.json name "${packageName}" does not match the requested npm package ${opts.expectPackageName}`;
+            throw new ApiError("extension.package_invalid", `Invalid extension package: ${issue}`, [
+                issue,
+            ]);
+        }
+        const declared = this.d.declared().get(m.name);
+        if (declared === "config") {
+            throw new ApiError("extension.config_declared", `Extension ${m.name} is declared in the startup config (extensions); remove it there before installing it as a package`);
+        }
+        const installed = await this.d.db
+            .selectFrom("extension_installs")
+            .innerJoin("extension_packages", "extension_packages.sha256", "extension_installs.sha256")
+            .select("extension_packages.package_name")
+            .where("extension_installs.name", "=", m.name)
+            .executeTakeFirst();
+        if (installed && installed.package_name !== packageName) {
+            throw new ApiError("extension.name_conflict", `Extension ${m.name} is already installed from package ${installed.package_name}; package ${packageName} uses the same extension name`);
+        }
+        // 写包之前在锁内复核发起人仍是企业管理员（守卫读到的身份可能已过期）；审计在写完后同样复核
+        if (actor !== null) {
+            await this.d.db.transaction().execute((trx) => lockEnterpriseAdminsAndAuthorize(trx, actor));
+        }
+        await this.d.blobs.put(pkg, bytes, {
+            source: src.source,
+            ref: src.ref,
+            actor,
+            ...(opts.store !== undefined && { store: opts.store }),
+        });
+        await this.d.db.transaction().execute(async (trx) => {
+            if (actor !== null)
+                await lockEnterpriseAdminsAndAuthorize(trx, actor);
+            await audit(trx, {
+                ...(actor !== null && { actorAccountId: actor }),
+                ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+                action: "extension.package_uploaded",
+                target: m.name,
+                detail: { name: m.name, version: m.version, sha256: pkg.sha256, source: src.source },
+            });
+        });
+        const set = permissionSetOfPackage(pkg);
+        const snapshot = (await new ExtensionApprovals(this.d.db).all()).get(m.name);
+        const { added, removed } = diffPermissions(snapshot?.permissions, set);
+        const warnings = migrationWarnings(pkg.migrationSql, m.name);
+        return {
+            sha256: pkg.sha256,
+            name: m.name,
+            version: m.version,
+            permissions: permissionGroups(set),
+            added,
+            addedItems: permissionKeyItems(added),
+            removed,
+            reviewHash: reviewHash(set, warnings),
+            warnings,
+        };
+    }
+    /** 上传的 tgz（来源 `file`）。 */
+    ingestFile(actor, bytes, opts = {}) {
+        return this.ingest(actor, bytes, { source: "file", ref: "upload" }, opts);
+    }
+    /**
+     * Fetches one package from the configured npm registry (verified by `dist.integrity`, see
+     * packages/npm.ts), downloading only, not storing: download failure -> `packages.npm_failed` (502);
+     * over `packages.maxBytes` -> `extension.package_too_large`. Enterprise catalog npm imports use it
+     * too.
+     */
+    async fetchNpm(input, signal) {
+        const c = this.d.config();
+        const cfg = {
+            registry: c.packages.npmRegistry,
+            maxBytes: c.packages.maxBytes,
+            ...(c.packages.npmToken !== undefined && { token: c.packages.npmToken }),
+        };
+        const timeout = AbortSignal.timeout(this.d.npmTimeoutMs ?? 120_000);
+        try {
+            return await fetchNpmPackage(cfg, input.package, input.version, signal ? AbortSignal.any([signal, timeout]) : timeout);
+        }
+        catch (e) {
+            if (e instanceof PackageTooLargeError) {
+                throw new ApiError("extension.package_too_large", e.message);
+            }
+            if (e instanceof NpmFetchError)
+                throw new ApiError("packages.npm_failed", e.message);
+            throw e;
+        }
+    }
+    /**
+     * Downloads the package of a marketplace npm source (T24, C26): from `tarball` when given (https
+     * required, `marketplaces.allowInsecureLoopback` for tests only; no registry metadata request;
+     * `packages.npmToken` is sent only when the tarball has the registry's origin), otherwise from the
+     * configured npm registry; always verified against the marketplace's sha512, never npm metadata.
+     * Mismatch -> 502 `marketplace.integrity_mismatch` (with prefixes of the expected and actual sha512);
+     * download failure -> 502 `marketplace.fetch_failed`; over `packages.maxBytes` ->
+     * `extension.package_too_large`.
+     */
+    fetchMarketplacePackage(input, signal) {
+        return this.fetchVerified(input, signal, {
+            mismatch: "marketplace.integrity_mismatch",
+            failed: "marketplace.fetch_failed",
+            against: "the marketplace",
+        });
+    }
+    /**
+     * The npm provenance of `name@version` from the configured registry (spec §5.5; display only,
+     * see packages/provenance.ts): bounded to {@link PROVENANCE_TIMEOUT_MS} and never throws, a
+     * failure is `{ checked: false, reason }`. `integrity` ties the statement to the tarball.
+     */
+    fetchProvenance(input, signal) {
+        const c = this.d.config();
+        const cfg = {
+            registry: c.packages.npmRegistry,
+            maxBytes: c.packages.maxBytes,
+            ...(c.packages.npmToken !== undefined && { token: c.packages.npmToken }),
+        };
+        const timeout = AbortSignal.timeout(PROVENANCE_TIMEOUT_MS);
+        return fetchProvenance(cfg, input.package, input.version, signal ? AbortSignal.any([signal, timeout]) : timeout, input.integrity !== undefined ? { integrity: input.integrity } : {});
+    }
+    async fetchVerified(input, signal, codes) {
+        const c = this.d.config();
+        const cfg = {
+            registry: c.packages.npmRegistry,
+            maxBytes: c.packages.maxBytes,
+            allowInsecureLoopback: c.marketplaces.allowInsecureLoopback,
+            ...(c.packages.npmToken !== undefined && { token: c.packages.npmToken }),
+        };
+        const timeout = AbortSignal.timeout(this.d.npmTimeoutMs ?? 120_000);
+        try {
+            return await fetchNpmPackage(cfg, input.package, input.version, signal ? AbortSignal.any([signal, timeout]) : timeout, {
+                expectedIntegrity: input.integrity,
+                ...(input.tarball !== undefined && { tarballUrl: input.tarball }),
+            });
+        }
+        catch (e) {
+            if (e instanceof PackageTooLargeError) {
+                throw new ApiError("extension.package_too_large", e.message);
+            }
+            if (e instanceof IntegrityMismatchError) {
+                const prefix = (sri) => `${sri.slice(0, 19)}…`;
+                throw new ApiError(codes.mismatch, `The package does not match ${codes.against} (expected ${prefix(e.expected)}, got ${prefix(e.actual)}); installation refused`, [{ expected: prefix(e.expected), actual: prefix(e.actual) }]);
+            }
+            if (e instanceof NpmFetchError)
+                throw new ApiError(codes.failed, e.message);
+            throw e;
+        }
+    }
+    /**
+     * Fetches from the configured npm registry (source `npm`, `ref` is `<package>@<version>`). Download
+     * failure -> `packages.npm_failed` (502); over the size limit -> `extension.package_too_large`; the
+     * npm name in the package differs from the requested one -> `extension.package_invalid`.
+     */
+    async ingestNpm(actor, input, opts = {}) {
+        const got = await this.fetchNpm(input, opts.signal);
+        return this.ingest(actor, got.bytes, { source: "npm", ref: `${input.package}@${got.version}` }, {
+            expectPackageName: input.package,
+            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            ...(opts.store !== undefined && { store: opts.store }),
+        });
+    }
+    /** 全部安装记录（按名字）。 */
+    async list() {
+        const rows = await this.d.db
+            .selectFrom("extension_installs")
+            .innerJoin("extension_packages", "extension_packages.sha256", "extension_installs.sha256")
+            .selectAll("extension_installs")
+            .select("extension_packages.package_name")
+            .orderBy("extension_installs.name")
+            .execute();
+        return rows.map((r) => ({
+            name: r.name,
+            sha256: r.sha256,
+            version: r.version,
+            source: r.source,
+            packageName: r.package_name,
+            desiredState: r.desired_state,
+            required: r.required,
+            migratedSha: r.migrated_sha,
+            installedBy: r.installed_by,
+            installedAt: r.installed_at.toISOString(),
+            updatedBy: r.updated_by,
+            updatedAt: r.updated_at.toISOString(),
+        }));
+    }
+    /** Install records desired enabled, with their reviewed extension sections (by name). */
+    async desired() {
+        const rows = await this.d.db
+            .selectFrom("extension_installs")
+            .innerJoin("extension_packages", "extension_packages.sha256", "extension_installs.sha256")
+            .select([
+            "extension_installs.name",
+            "extension_installs.sha256",
+            "extension_installs.version",
+            "extension_installs.source",
+            "extension_installs.migrated_sha",
+            "extension_packages.section",
+            "extension_packages.blob_store",
+        ])
+            .where("extension_installs.desired_state", "=", "enabled")
+            .orderBy("extension_installs.name")
+            .execute();
+        return rows.map((r) => ({
+            name: r.name,
+            sha256: r.sha256,
+            version: r.version,
+            source: r.source,
+            migratedSha: r.migrated_sha,
+            blobStore: r.blob_store,
+            section: r.section,
+        }));
+    }
+}

package/dist/extensions/instance.d.ts

@@ -0,0 +1,167 @@
+import { type ExtensionManifest, type ExtensionPointRef, type StaticExtensionManifest } from "@capybara-hq/plugin-sdk";
+import { type ExtensionPointAccess, type KernelDeps, type KernelExtensionContext, LiveConfig, type RegisteredTool, type Route } from "../ctx/create-ctx.js";
+import type { UiActionHandler, UiRender } from "../ui/registry.js";
+import type { RegisteredHook } from "./hooks.js";
+import { InflightTracker } from "./inflight.js";
+import type { Registration } from "./ledger.js";
+import type { PermissionSet } from "./permission-set.js";
+import type { ExtensionSource } from "./sources.js";
+export type { Registration, RegistrationKind } from "./ledger.js";
+/** 模块清单与审阅过的静态清单（包内 `capybara.manifest`）不一致。 */
+export declare class ManifestMismatchError extends Error {
+    constructor(plugin: string, moduleName: string);
+}
+/** 模块清单与审阅过的静态清单是否一致（名字与 {@link staticManifestOf} 都须相同）。 */
+export declare function matchesSection(manifest: ExtensionManifest, name: string, section: StaticExtensionManifest): boolean;
+/** 导入一个插件模块（default 导出）并按 defineExtension 校验清单。 */
+export declare function importExtensionModule(url: string, label: string, resolveFrom: string): Promise<ExtensionManifest>;
+/** Constructor parameters of {@link ExtensionInstance} (kernel internal). */
+export interface ExtensionInstanceInit {
+    manifest: ExtensionManifest;
+    source: ExtensionSource;
+    sha256: string | null;
+    generation: number;
+    permissions: PermissionSet;
+    /** 部署配置摘要（见 `deploymentConfigHash`）。 */
+    configHash: string;
+    /** 已按清单 schema 校验的部署配置（含密钥）；与 ctx 共用同一个 {@link LiveConfig}。 */
+    config: LiveConfig;
+    /** 模块入口（`file:` URL）：同进程重新加载时用。 */
+    entryUrl: string;
+    ctx: KernelExtensionContext;
+    log: KernelDeps["log"];
+}
+/**
+ * 一个已完成 setup 的插件实例（一代）：清单、来源、权限、部署配置，以及它经 ctx 做过的全部登记（账）。
+ * 同一插件升级 / 重新加载会产生新实例（generation 加一），旧实例 `dispose` 后它的登记全部撤销；
+ * 旧模块代码留在内存里直到进程重启（ESM 无法卸载）。
+ */
+export declare class ExtensionInstance {
+    readonly name: string;
+    readonly version: string;
+    readonly sha256: string | null;
+    readonly source: ExtensionSource;
+    readonly generation: number;
+    readonly manifest: ExtensionManifest;
+    readonly permissions: PermissionSet;
+    private hash;
+    private readonly live;
+    readonly entryUrl: string;
+    readonly inflight: InflightTracker;
+    private readonly ctx;
+    private readonly log;
+    private disposing;
+    /** {@link hurry}：进行中的 dispose 不再等排空时限。 */
+    private readonly hurried;
+    constructor(init: ExtensionInstanceInit);
+    /** 此刻的部署配置（hot 改动后是新值）。 */
+    get config(): unknown;
+    /** 部署配置摘要（见 `deploymentConfigHash`；hot 改动后随之更新）。 */
+    get configHash(): string;
+    /** hot 字段改动：就地替换部署配置（插件下次读 `ctx.config` 拿到新值），不重新 setup（C10）。 */
+    updateConfig(config: unknown, configHash: string): void;
+    /** 提供的能力（撤销后为空）。 */
+    get provided(): ReadonlyMap<ExtensionPointRef, unknown>;
+    get routes(): readonly Route[];
+    get tools(): readonly RegisteredTool[];
+    /** Hooks registered through `ctx.hooks.on` (empty after revocation). */
+    get hooks(): readonly RegisteredHook[];
+    get uiViews(): ReadonlyMap<string, UiRender>;
+    get uiActions(): ReadonlyMap<string, UiActionHandler>;
+    /** 账上仍在的登记（撤销后为空）。 */
+    registrations(): Registration[];
+    get disposed(): boolean;
+    /**
+     * Revokes this instance (idempotent; the caller should first remove it from the registry or replace
+     * it). In order:
+     * 1. stop taking new work (in-flight tracker closed, queue workers stop taking new jobs);
+     * 2. wait for in-flight tool calls and running queue worker jobs together, up to `drainMs` (one
+     *    deadline);
+     * 3. abort: remaining in-flight calls end with `ExtensionUnloadedError` (the model gets
+     *    `PLUGIN_UNLOADED_TOOL_ERROR`), `ctx.signal` aborts (so work that honours `ctx.signal` is not
+     *    aborted within the drain limit);
+     * 4. revoke the ledger's registrations one by one (in reverse; queue jobs still running at the
+     *    deadline are forced to stay in the queue);
+     * 5. call the extension's `dispose(ctx)`, up to `disposeTimeoutMs` (a throw or timeout is only
+     *    logged, and it goes on);
+     * 6. close the ctx (queue connections, pending audit writes). Step 6 throws on failure (the caller
+     *    logs it).
+     * `waitQueueJobs` (shutdown path): queue workers wait for running jobs to finish instead of being
+     * force-closed at the deadline.
+     */
+    dispose(opts: DisposeOptions): Promise<void>;
+    /**
+     * 让进行中（或之后开始）的 {@link dispose} 立即结束排空：余下的在途调用随即中止，队列任务按到时处理
+     * （停机时宿主对后台撤销中的旧实例调用）。没有在撤销时等同于以排空时限 0 撤销。
+     */
+    hurry(): Promise<void>;
+    private doDispose;
+}
+/** 插件 `dispose()` 的默认时限（`extensionHost.disposeTimeoutSeconds` 的默认值）。 */
+export declare const DEFAULT_DISPOSE_TIMEOUT_MS = 10000;
+/** Parameters of {@link ExtensionInstance.dispose}. */
+export interface DisposeOptions {
+    /** 在途调用与队列任务的排空时限（毫秒）。 */
+    drainMs: number;
+    /** 插件 `dispose()` 的时限（毫秒），默认 {@link DEFAULT_DISPOSE_TIMEOUT_MS}。 */
+    disposeTimeoutMs?: number;
+    /** 停机路径：队列 worker 一直等进行中的任务结束，不按截止时刻强制关闭。 */
+    waitQueueJobs?: boolean;
+}
+/** 同进程导入过的插件模块数超过多少（每个插件第一个入口不算）就告警。 */
+export declare const UPGRADE_WARN_THRESHOLD = 20;
+/**
+ * 记录本进程导入过的插件模块入口（按插件名去重的 URL）：ESM 模块无法卸载，每个新入口（升级到新包）
+ * 的代码都留在内存里直到进程重启。同一 URL 的重新加载不新增模块，不计数。
+ * 升级数 = 各插件「不同入口数 - 1」之和；第一次超过 {@link UPGRADE_WARN_THRESHOLD} 时 `record` 返回 true（只一次）。
+ */
+export declare class ImportTracker {
+    private readonly urls;
+    private warned;
+    /** 本进程的升级数（见类注释）。 */
+    get upgrades(): number;
+    /** 记一次导入；返回这次是否应当告警。 */
+    record(plugin: string, url: string): boolean;
+}
+/** 升级次数超过阈值的告警（旧模块代码留在内存直到重启）。 */
+export declare function warnUpgrades(log: KernelDeps["log"], imports: ImportTracker): void;
+/** {@link setupInstance} / {@link loadInstance} 的依赖。 */
+export interface LoadDeps {
+    kernel: KernelDeps;
+    extensionPointAccess: ExtensionPointAccess;
+    /** 该插件下一代的编号（宿主按插件名递增）。 */
+    nextGeneration(name: string): number;
+    /** 本进程导入过的模块入口（{@link loadInstance} 每次导入都记一笔，超过阈值时告警）。 */
+    imports?: ImportTracker;
+}
+/** 在已导入、已核对的清单上建 ctx（记账）并 setup；setup 抛错时撤销已登记的再抛。 */
+export declare function setupInstance(deps: LoadDeps, manifest: ExtensionManifest, input: {
+    entryUrl: string;
+    source: ExtensionSource;
+    sha256: string | null;
+    config: unknown;
+    configHash: string;
+    permissions: PermissionSet;
+    /** 已建好 ctx、setup 进行中时回调（宿主据此在 close() 时立即关闭它）。 */
+    onCtx?: (ctx: KernelExtensionContext | undefined) => void;
+}): Promise<ExtensionInstance>;
+/**
+ * 加载一个插件实例：import → defineExtension → 有包内静态清单（`section`）时与 {@link staticManifestOf} 核对
+ * （名字与静态清单都须一致，否则抛 {@link ManifestMismatchError}；配置声明 / 内置插件没有 section，跳过核对）
+ * → 建 ctx（记账）→ setup；setup 抛错时撤销已登记的再抛。
+ * 不做权限闸门、部署配置校验与迁移（宿主在此之前完成）；`config` 为已校验的部署配置。
+ */
+export declare function loadInstance(deps: LoadDeps, input: {
+    entryUrl: string;
+    source: ExtensionSource;
+    sha256: string | null;
+    config: unknown;
+    configHash: string;
+    permissions: PermissionSet;
+    /** 安装记录的包内静态清单与插件名（审阅过的那份）。 */
+    section?: {
+        name: string;
+        manifest: StaticExtensionManifest;
+    };
+    onCtx?: (ctx: KernelExtensionContext | undefined) => void;
+}): Promise<ExtensionInstance>;