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

package/dist/catalog/marketplace-fetch.js

@@ -0,0 +1,203 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { parseMarketplaceManifest } from "@capybara-hq/plugin-sdk";
+import { ApiError } from "../errors.js";
+import { NetDeniedError } from "../net/public-address.js";
+import { safeFetch } from "../net/safe-fetch.js";
+import { isLoopback, readCapped } from "../packages/npm.js";
+/**
+ * The API error for a refused download, or undefined when the refusal is not one of the two
+ * marketplace codes (an invalid URL or a DNS failure is an ordinary fetch failure).
+ */
+export function marketplaceNetCode(e) {
+    if (e.code === "net.private_address")
+        return "marketplace.private_address";
+    if (e.code === "net.redirect")
+        return "marketplace.redirect";
+    return undefined;
+}
+/** The network rules for marketplace downloads from the kernel config. */
+export function marketplaceNetPolicy(config) {
+    return {
+        allowInsecureLoopback: config.marketplaces.allowInsecureLoopback,
+        allowPrivateHosts: config.marketplaces.allowPrivateHosts,
+        trustedOrigins: [new URL(config.packages.npmRegistry).origin],
+        ...(config.net.httpsProxy !== undefined && {
+            proxy: { url: config.net.httpsProxy, noProxy: config.net.noProxy },
+        }),
+    };
+}
+/**
+ * The fetch failed (network, HTTP status, redirect, size, timeout). English message, no token.
+ * `code` is set when the network rules refused the request.
+ */
+export class MarketplaceFetchError extends Error {
+    code;
+    /** The host the network rules refused (with `code`). */
+    host;
+    constructor(message, options) {
+        super(message, options);
+        this.name = "MarketplaceFetchError";
+        this.code = options?.code;
+        this.host = options?.host;
+    }
+}
+/** The response is not a valid manifest (JSON or schema). */
+export class MarketplaceInvalidError extends Error {
+    issues;
+    constructor(message, issues) {
+        super(message);
+        this.issues = issues;
+        this.name = "MarketplaceInvalidError";
+    }
+}
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+/**
+ * Whether a marketplace URL is usable: https (or http on loopback in tests), at most 2000
+ * characters, parseable, without user info. Returns the reason (English) or null.
+ */
+export function marketplaceUrlProblem(url, allowInsecureLoopback) {
+    if (url.length > 2000)
+        return "the URL is longer than 2000 characters";
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return "not a valid URL";
+    }
+    if (u.username !== "" || u.password !== "")
+        return "the URL must not contain credentials";
+    if (u.protocol === "https:")
+        return null;
+    if (allowInsecureLoopback && u.protocol === "http:" && isLoopback(u.hostname))
+        return null;
+    return "the URL must use https";
+}
+/**
+ * Fetches and validates one `marketplace.json`. Throws {@link MarketplaceFetchError} or
+ * {@link MarketplaceInvalidError}.
+ */
+export async function fetchMarketplaceManifest(url, o) {
+    const problem = marketplaceUrlProblem(url, o.net.allowInsecureLoopback);
+    if (problem !== null)
+        throw new MarketplaceFetchError(`invalid marketplace URL: ${problem}`);
+    const target = new URL(url);
+    const headers = { accept: "application/json" };
+    if (o.etag)
+        headers["if-none-match"] = o.etag;
+    if (o.token !== undefined && o.tokenOrigin === target.origin) {
+        headers.authorization = `Bearer ${o.token}`;
+    }
+    const signal = AbortSignal.any([o.signal, AbortSignal.timeout(o.timeoutMs)]);
+    let res;
+    try {
+        res = await safeFetch(target.href, { headers, signal }, o.net, {
+            ...(o.lookup !== undefined && { lookup: o.lookup }),
+        });
+    }
+    catch (e) {
+        if (e instanceof NetDeniedError) {
+            const code = marketplaceNetCode(e);
+            throw new MarketplaceFetchError(`cannot fetch the marketplace: ${e.message}`, {
+                cause: e,
+                ...(code !== undefined && { code, host: e.host }),
+            });
+        }
+        throw new MarketplaceFetchError(`cannot fetch the marketplace: ${errMsg(e)}`, { cause: e });
+    }
+    if (res.status === 304) {
+        await res.body?.cancel().catch(() => { });
+        return { status: "not_modified" };
+    }
+    if (!res.ok) {
+        await res.body?.cancel().catch(() => { });
+        throw new MarketplaceFetchError(`the marketplace responded with HTTP ${res.status}`);
+    }
+    let raw;
+    try {
+        raw = await readCapped(res, o.maxBytes, () => new MarketplaceFetchError(`the marketplace is larger than ${o.maxBytes} bytes`));
+    }
+    catch (e) {
+        if (e instanceof MarketplaceFetchError)
+            throw e;
+        throw new MarketplaceFetchError(`cannot read the marketplace: ${errMsg(e)}`, { cause: e });
+    }
+    let json;
+    try {
+        json = JSON.parse(raw.toString("utf8"));
+    }
+    catch {
+        throw new MarketplaceInvalidError("the marketplace manifest is not valid JSON", []);
+    }
+    const parsed = parseMarketplaceManifest(json, {
+        allowInsecureLoopback: o.net.allowInsecureLoopback,
+    });
+    if ("errors" in parsed) {
+        throw new MarketplaceInvalidError(`the response is not a valid marketplace.json: ${parsed.errors.slice(0, 5).join("; ")}`, parsed.errors);
+    }
+    return { status: "ok", manifest: parsed, etag: res.headers.get("etag") };
+}
+/** `sha512-<base64>` / `sha256-<base64>` SRI -> algorithm and digest (undefined otherwise). */
+function parseSri(integrity) {
+    const m = /^(sha512|sha256)-([A-Za-z0-9+/]+={0,2})$/.exec(integrity.trim());
+    if (!m)
+        return undefined;
+    const alg = m[1];
+    const digest = Buffer.from(m[2], "base64");
+    return digest.length === (alg === "sha512" ? 64 : 32) ? { alg, digest } : undefined;
+}
+/**
+ * Downloads a marketplace `archive` source (a plugin tgz at `url`) under the rules in the file
+ * header (https, no redirects, at most `maxBytes`, a timeout) and verifies it against the
+ * marketplace's `integrity` (sha512 or sha256 SRI). Failures are API errors: a size over the limit
+ * -> `extension.package_too_large`; a digest mismatch -> `marketplace.integrity_mismatch`; a host
+ * resolving to a private address -> `marketplace.private_address`; a 3xx -> `marketplace.redirect`;
+ * anything else -> `marketplace.fetch_failed`.
+ */
+export async function fetchMarketplaceArchive(archive, o) {
+    const failed = (m) => new ApiError("marketplace.fetch_failed", m);
+    const problem = marketplaceUrlProblem(archive.url, o.net.allowInsecureLoopback);
+    if (problem !== null)
+        throw failed(`invalid archive URL: ${problem}`);
+    const sri = parseSri(archive.integrity);
+    if (!sri)
+        throw failed("the archive integrity is not a sha512 or sha256 SRI");
+    const timeout = AbortSignal.timeout(o.timeoutMs);
+    const signal = o.signal ? AbortSignal.any([o.signal, timeout]) : timeout;
+    let res;
+    try {
+        res = await safeFetch(new URL(archive.url).href, { signal }, o.net, {
+            ...(o.lookup !== undefined && { lookup: o.lookup }),
+        });
+    }
+    catch (e) {
+        if (e instanceof NetDeniedError) {
+            const code = marketplaceNetCode(e);
+            if (code !== undefined) {
+                throw new ApiError(code, `Archive download refused: ${e.message}`, [{ host: e.host }]);
+            }
+        }
+        throw failed(`cannot fetch the archive: ${errMsg(e)}`);
+    }
+    if (!res.ok) {
+        await res.body?.cancel().catch(() => { });
+        throw failed(`the archive URL responded with HTTP ${res.status}`);
+    }
+    const tooLarge = new ApiError("extension.package_too_large", `the package is larger than ${o.maxBytes} bytes`);
+    let bytes;
+    try {
+        bytes = await readCapped(res, o.maxBytes, () => tooLarge);
+    }
+    catch (e) {
+        if (e === tooLarge)
+            throw e;
+        throw failed(`cannot read the archive: ${errMsg(e)}`);
+    }
+    const got = createHash(sri.alg).update(bytes).digest();
+    if (!timingSafeEqual(got, sri.digest)) {
+        const prefix = (s) => `${s.slice(0, 19)}…`;
+        const actual = `${sri.alg}-${got.toString("base64")}`;
+        throw new ApiError("marketplace.integrity_mismatch", `The package does not match the marketplace (expected ${prefix(archive.integrity)}, got ${prefix(actual)}); installation refused`, [{ expected: prefix(archive.integrity), actual: prefix(actual) }]);
+    }
+    return { bytes: new Uint8Array(bytes), integrity: archive.integrity };
+}

package/dist/catalog/marketplaces.controller.d.ts

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import { type KernelConfig } from "../config/schema.js";
+import { type Principal } from "../identity/principal.js";
+import type { CatalogService, MarketplaceImportResult } from "./catalog.service.js";
+import type { MarketplaceEntryView, MarketplacesService, MarketplaceView } from "./marketplaces.service.js";
+declare const AddBody: z.ZodObject<{
+    name: z.ZodString;
+    url: z.ZodString;
+    form: z.ZodOptional<z.ZodEnum<{
+        git: "git";
+        http: "http";
+    }>>;
+    ref: z.ZodOptional<z.ZodString>;
+    mirrors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    token: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const PatchBody: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    form: z.ZodOptional<z.ZodEnum<{
+        git: "git";
+        http: "http";
+    }>>;
+    ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    mirrors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+declare const EntriesQuery: z.ZodObject<{
+    sourceId: z.ZodOptional<z.ZodString>;
+    q: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const ImportBody: z.ZodObject<{
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Marketplaces (`/api/v1/admin/marketplaces/*`, enterprise admins): create, update, delete and
+ * refresh the official and enterprise marketplaces, browse entries, import from a marketplace.
+ * Writes re-check the enterprise admin inside the service's lock and are audited.
+ */
+export declare class MarketplacesController {
+    private readonly marketplaces;
+    private readonly catalog;
+    private readonly config;
+    constructor(marketplaces: MarketplacesService, catalog: CatalogService, config: () => KernelConfig);
+    /** 全部来源；`offline` 为 true 表示 `marketplaces.official.enabled` 为 false（界面显示「离线模式」）。 */
+    list(): Promise<{
+        items: MarketplaceView[];
+        offline: boolean;
+    }>;
+    /**
+     * Adds an enterprise marketplace (https URL and mirrors; the token is kept in secrets and sent only
+     * to the URL's origin). A git URL (`…/*.git`, `owner/repo`, or any URL with `form: "git"`) is a
+     * git marketplace with an optional `ref`; anything else is a marketplace.json URL.
+     */
+    add(principal: Principal, body: z.infer<typeof AddBody>): Promise<MarketplaceView>;
+    /**
+     * Browses entries (enabled marketplaces only, `sourceId` filters by marketplace; at most
+     * `MARKETPLACE_ENTRIES_MAX`, `truncated` true means there are more). An entry that cannot be
+     * imported has `importable: false` and a `reason`: `host_not_allowed` (its git / archive host is
+     * outside `marketplaces.allowedHosts`) or `path_needs_git_marketplace` (a path entry of an http
+     * marketplace).
+     */
+    entries(q: z.infer<typeof EntriesQuery>): Promise<{
+        items: MarketplaceEntryView[];
+        truncated: boolean;
+    }>;
+    /**
+     * Updates a marketplace (official only takes `enabled`, anything else -> 409
+     * `marketplace.builtin`; `token: null` clears the token).
+     */
+    update(principal: Principal, id: string, body: z.infer<typeof PatchBody>): Promise<MarketplaceView>;
+    /**
+     * Deletes an enterprise marketplace (imported catalog items are kept); official -> 409
+     * `marketplace.builtin`.
+     */
+    remove(principal: Principal, id: string): Promise<void>;
+    /**
+     * Manual refresh (a git marketplace with an unchanged commit is skipped). On failure the status
+     * becomes `error`, the old entries are kept, and it returns `marketplace.invalid` (502) when some
+     * URL returned an invalid manifest, the network rule's code (422) when every URL was refused by
+     * it, a git reader code (`marketplace.git_failed` 502, `git_too_large` / `git_unsupported_entry`
+     * 422) for a git marketplace, else `marketplace.fetch_failed` (502).
+     */
+    refresh(principal: Principal, id: string): Promise<MarketplaceView>;
+    /**
+     * Prepares the import of one version of a marketplace entry (`version` defaults to the newest
+     * compatible one; verified against the marketplace's integrity): 200 `{ stagingId, review,
+     * permissionsMismatch }`, confirmed with `POST /api/v1/admin/catalog/imports/:stagingId/confirm`.
+     * A `path` / `git` source is read from git (a path at the marketplace's last refreshed commit, a
+     * git source at its pinned commit or its ref's head, recorded); its host outside
+     * `marketplaces.allowedHosts` -> 403 `marketplace.host_not_allowed`; a path entry of an http
+     * marketplace -> 422 `marketplace.path_unsupported`.
+     */
+    importEntry(principal: Principal, id: string, name: string, body: z.infer<typeof ImportBody>): Promise<MarketplaceImportResult>;
+}
+export {};

package/dist/catalog/marketplaces.controller.js

@@ -0,0 +1,197 @@
+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 { Body, Controller, Delete, Get, HttpCode, Inject, Param, Patch, Post, Query, } from "@nestjs/common";
+import { z } from "zod";
+import { MARKETPLACE_MAX_MIRRORS } from "../config/schema.js";
+import { CATALOG, KERNEL_CONFIG, MARKETPLACES } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { CurrentPrincipal, EnterpriseAdmin, patTokenId, requireUser, } from "../identity/principal.js";
+const Url = z.string().min(1).max(2000);
+const Form = z.enum(["http", "git"]);
+const Ref = z.string().min(1).max(256);
+const AddBody = z.object({
+    name: z.string().min(1).max(100),
+    url: Url,
+    form: Form.optional(),
+    ref: Ref.optional(),
+    mirrors: z.array(Url).max(MARKETPLACE_MAX_MIRRORS).optional(),
+    token: z.string().min(1).max(4096).optional(),
+});
+const PatchBody = z
+    .object({
+    name: z.string().min(1).max(100).optional(),
+    url: Url.optional(),
+    form: Form.optional(),
+    ref: Ref.nullable().optional(),
+    mirrors: z.array(Url).max(MARKETPLACE_MAX_MIRRORS).optional(),
+    enabled: z.boolean().optional(),
+    token: z.string().min(1).max(4096).nullable().optional(),
+})
+    .strict();
+const EntriesQuery = z.object({
+    sourceId: z.string().min(1).max(100).optional(),
+    q: z.string().max(200).optional(),
+});
+const ImportBody = z.object({ version: z.string().min(1).max(256).optional() });
+/** 手动刷新的总时限（每个地址另有 30 秒超时）。 */
+const REFRESH_DEADLINE_MS = 300_000;
+const actorOpts = (actor) => {
+    const tokenId = patTokenId(actor);
+    return tokenId !== undefined ? { actorTokenId: tokenId } : {};
+};
+/**
+ * Marketplaces (`/api/v1/admin/marketplaces/*`, enterprise admins): create, update, delete and
+ * refresh the official and enterprise marketplaces, browse entries, import from a marketplace.
+ * Writes re-check the enterprise admin inside the service's lock and are audited.
+ */
+let MarketplacesController = class MarketplacesController {
+    marketplaces;
+    catalog;
+    config;
+    constructor(marketplaces, catalog, config) {
+        this.marketplaces = marketplaces;
+        this.catalog = catalog;
+        this.config = config;
+    }
+    /** 全部来源；`offline` 为 true 表示 `marketplaces.official.enabled` 为 false（界面显示「离线模式」）。 */
+    async list() {
+        return {
+            items: await this.marketplaces.list(),
+            offline: !this.config().marketplaces.official.enabled,
+        };
+    }
+    /**
+     * Adds an enterprise marketplace (https URL and mirrors; the token is kept in secrets and sent only
+     * to the URL's origin). A git URL (`…/*.git`, `owner/repo`, or any URL with `form: "git"`) is a
+     * git marketplace with an optional `ref`; anything else is a marketplace.json URL.
+     */
+    add(principal, body) {
+        const actor = requireUser(principal);
+        return this.marketplaces.add(actor.account.id, {
+            name: body.name,
+            url: body.url,
+            ...(body.form !== undefined && { form: body.form }),
+            ...(body.ref !== undefined && { ref: body.ref }),
+            ...(body.mirrors !== undefined && { mirrors: body.mirrors }),
+            ...(body.token !== undefined && { token: body.token }),
+        }, actorOpts(actor));
+    }
+    /**
+     * Browses entries (enabled marketplaces only, `sourceId` filters by marketplace; at most
+     * `MARKETPLACE_ENTRIES_MAX`, `truncated` true means there are more). An entry that cannot be
+     * imported has `importable: false` and a `reason`: `host_not_allowed` (its git / archive host is
+     * outside `marketplaces.allowedHosts`) or `path_needs_git_marketplace` (a path entry of an http
+     * marketplace).
+     */
+    entries(q) {
+        return this.marketplaces.entries({
+            ...(q.sourceId !== undefined && { marketplaceId: q.sourceId }),
+            ...(q.q !== undefined && { q: q.q }),
+        });
+    }
+    /**
+     * Updates a marketplace (official only takes `enabled`, anything else -> 409
+     * `marketplace.builtin`; `token: null` clears the token).
+     */
+    update(principal, id, body) {
+        const actor = requireUser(principal);
+        return this.marketplaces.update(actor.account.id, id, {
+            ...(body.name !== undefined && { name: body.name }),
+            ...(body.url !== undefined && { url: body.url }),
+            ...(body.form !== undefined && { form: body.form }),
+            ...(body.ref !== undefined && { ref: body.ref }),
+            ...(body.mirrors !== undefined && { mirrors: body.mirrors }),
+            ...(body.enabled !== undefined && { enabled: body.enabled }),
+            ...(body.token !== undefined && { token: body.token }),
+        }, actorOpts(actor));
+    }
+    /**
+     * Deletes an enterprise marketplace (imported catalog items are kept); official -> 409
+     * `marketplace.builtin`.
+     */
+    async remove(principal, id) {
+        const actor = requireUser(principal);
+        await this.marketplaces.remove(actor.account.id, id, actorOpts(actor));
+    }
+    /**
+     * Manual refresh (a git marketplace with an unchanged commit is skipped). On failure the status
+     * becomes `error`, the old entries are kept, and it returns `marketplace.invalid` (502) when some
+     * URL returned an invalid manifest, the network rule's code (422) when every URL was refused by
+     * it, a git reader code (`marketplace.git_failed` 502, `git_too_large` / `git_unsupported_entry`
+     * 422) for a git marketplace, else `marketplace.fetch_failed` (502).
+     */
+    refresh(principal, id) {
+        const actor = requireUser(principal);
+        return this.marketplaces.refresh(id, AbortSignal.timeout(REFRESH_DEADLINE_MS), actor.account.id, {
+            ...actorOpts(actor),
+            throwOnError: true,
+        });
+    }
+    /**
+     * Prepares the import of one version of a marketplace entry (`version` defaults to the newest
+     * compatible one; verified against the marketplace's integrity): 200 `{ stagingId, review,
+     * permissionsMismatch }`, confirmed with `POST /api/v1/admin/catalog/imports/:stagingId/confirm`.
+     * A `path` / `git` source is read from git (a path at the marketplace's last refreshed commit, a
+     * git source at its pinned commit or its ref's head, recorded); its host outside
+     * `marketplaces.allowedHosts` -> 403 `marketplace.host_not_allowed`; a path entry of an http
+     * marketplace -> 422 `marketplace.path_unsupported`.
+     */
+    importEntry(principal, id, name, body) {
+        const actor = requireUser(principal);
+        return this.catalog.importFromMarketplace(actor.account.id, { marketplaceId: id, name, ...(body.version !== undefined && { version: body.version }) }, actorOpts(actor));
+    }
+};
+__decorate([
+    Get()
+], MarketplacesController.prototype, "list", null);
+__decorate([
+    Post(),
+    HttpCode(201),
+    __param(0, CurrentPrincipal()),
+    __param(1, Body(new ZodPipe(AddBody)))
+], MarketplacesController.prototype, "add", null);
+__decorate([
+    Get("entries"),
+    __param(0, Query(new ZodPipe(EntriesQuery)))
+], MarketplacesController.prototype, "entries", null);
+__decorate([
+    Patch(":id"),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("id")),
+    __param(2, Body(new ZodPipe(PatchBody)))
+], MarketplacesController.prototype, "update", null);
+__decorate([
+    Delete(":id"),
+    HttpCode(204),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("id"))
+], MarketplacesController.prototype, "remove", null);
+__decorate([
+    Post(":id/refresh"),
+    HttpCode(200),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("id"))
+], MarketplacesController.prototype, "refresh", null);
+__decorate([
+    Post(":id/entries/:name/import"),
+    HttpCode(200),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("id")),
+    __param(2, Param("name")),
+    __param(3, Body(new ZodPipe(ImportBody)))
+], MarketplacesController.prototype, "importEntry", null);
+MarketplacesController = __decorate([
+    Controller("api/v1/admin/marketplaces"),
+    EnterpriseAdmin(),
+    __param(0, Inject(MARKETPLACES)),
+    __param(1, Inject(CATALOG)),
+    __param(2, Inject(KERNEL_CONFIG))
+], MarketplacesController);
+export { MarketplacesController };