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

package/dist/catalog/git-source.js

@@ -0,0 +1,520 @@
+import * as fsp from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { inflateSync } from "node:zlib";
+import git, {} from "isomorphic-git";
+import { NetDeniedError } from "../net/public-address.js";
+import { NetBodyTooLargeError, safeFetch } from "../net/safe-fetch.js";
+import { marketplaceNetCode, marketplaceUrlProblem, } from "./marketplace-fetch.js";
+/**
+ * Reading plugins from git (spec §5.1, §5.2; Decision 2): isomorphic-git (pure JS, any smart-HTTP
+ * host) over the kernel's public-address network layer. The repo is hostile input:
+ * - https smart HTTP only (`GET info/refs` + `POST git-upload-pack`), each request through
+ *   `net/safeFetch` (public addresses, pinned connection, no redirects); the token goes only to
+ *   `tokenOrigin`;
+ * - one commit, depth 1, no tags, no submodules (never fetched); the pack is at most `maxBytes`;
+ * - before isomorphic-git indexes the pack (which inflates every object), the pack is scanned with
+ *   bounded inflation: at most {@link GIT_LIMITS}`.maxObjects` objects and 4 × `maxBytes` of declared
+ *   content in all, so a deflate bomb is refused before it is expanded;
+ * - files are read from the object store (`readTree` / `readBlob`), never checked out; symlinks and
+ *   submodule entries under `path` are refused; at most 5000 files and 4 × `maxBytes`; LFS pointer
+ *   files are ordinary files;
+ * - the object store is a temp dir removed after each operation; 120 s per operation.
+ */
+export const GIT_LIMITS = {
+    maxFiles: 5000,
+    /** Objects in one pack (a depth-1 commit: the commit, its trees and blobs). */
+    maxObjects: 20_000,
+    /** Unpacked bytes (pack content and files read) at most this × `maxBytes`. */
+    unpackedFactor: 4,
+    timeoutMs: 120_000,
+};
+/** `./a/b/` -> `a/b`; the root is `.`. */
+export const normalGitPath = (path) => {
+    const p = (path ?? ".").replace(/^\.\//, "").replace(/\/+$/, "");
+    return p === "" ? "." : p;
+};
+/**
+ * The identity of a git location, `<host>/<repo>:<path>` (host lower case, the repo without a
+ * leading `/` or a trailing `.git`, `path` as {@link normalGitPath}).
+ */
+export function gitLocationIdentity(l) {
+    return `${l.host.toLowerCase()}/${l.repo.replace(/^\/+/, "").replace(/\.git$/, "")}:${normalGitPath(l.path)}`;
+}
+/** {@link gitLocationIdentity} of a repo URL and a path in it. */
+export function gitUrlIdentity(url, path) {
+    const u = new URL(url);
+    return gitLocationIdentity({ host: u.host, repo: u.pathname, path: normalGitPath(path) });
+}
+/** A git read failed. English message without the token; `netCode` when the network rules refused. */
+export class GitSourceError extends Error {
+    code;
+    netCode;
+    detail;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "GitSourceError";
+        this.netCode = options?.netCode;
+        this.detail = options?.detail ?? {};
+    }
+}
+/**
+ * The details of a git failure's API error: the host (the one the network rules refused, else the
+ * repo's), the repo path, the ref or commit asked for, and the refused entry. Lets the web name them
+ * in localized copy; the English message stays for logs and API users.
+ */
+export function gitErrorDetails(e, loc) {
+    let host = e.detail.host;
+    let repo;
+    try {
+        const u = new URL(loc.url);
+        host ??= u.hostname;
+        repo = u.pathname
+            .replace(/\/+$/, "")
+            .replace(/\.git$/, "")
+            .replace(/^\/+/, "");
+    }
+    catch {
+        // not a URL: the message says so
+    }
+    return {
+        ...(host !== undefined && host !== "" && { host }),
+        ...(repo !== undefined && repo !== "" && { repo }),
+        ...(loc.ref !== undefined && { ref: loc.ref }),
+        ...(loc.commit !== undefined && { commit: loc.commit }),
+        ...(e.detail.path !== undefined && { path: e.detail.path }),
+        ...(e.detail.hint !== undefined && { hint: e.detail.hint }),
+    };
+}
+const SHA_RE = /^[0-9a-f]{40}$/i;
+const SHORTHAND_RE = /^([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\/([A-Za-z0-9_.-]{1,100})$/;
+/** `owner/repo` -> `https://github.com/owner/repo.git`; anything else is returned unchanged. */
+export function expandGitUrl(input) {
+    const m = SHORTHAND_RE.exec(input);
+    if (m === null)
+        return input;
+    const repo = m[2].replace(/\.git$/, "");
+    if (repo === "" || repo === "." || repo === "..")
+        return input;
+    return `https://github.com/${m[1]}/${repo}.git`;
+}
+const failed = (message, cause) => new GitSourceError("marketplace.git_failed", message, cause === undefined ? {} : { cause });
+const tooLarge = (message) => new GitSourceError("marketplace.git_too_large", message);
+const unsupported = (message, path) => new GitSourceError("marketplace.git_unsupported_entry", message, { detail: { path } });
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+async function collect(body) {
+    const parts = [];
+    if (body !== undefined)
+        for await (const c of body)
+            parts.push(c);
+    return Buffer.concat(parts);
+}
+function startOp(loc, o) {
+    const problem = marketplaceUrlProblem(loc.url, o.net.allowInsecureLoopback);
+    if (problem !== null)
+        throw failed(`invalid git URL: ${problem}`);
+    const signal = AbortSignal.any([o.signal, AbortSignal.timeout(GIT_LIMITS.timeoutMs)]);
+    const state = { overLimit: false };
+    const auth = o.token === undefined
+        ? undefined
+        : `Basic ${Buffer.from(`x-access-token:${o.token}`).toString("base64")}`;
+    const http = {
+        async request(req) {
+            const target = new URL(req.url);
+            const headers = { ...req.headers };
+            delete headers.authorization;
+            delete headers.Authorization;
+            if (auth !== undefined && o.tokenOrigin === target.origin)
+                headers.authorization = auth;
+            const method = req.method ?? "GET";
+            const body = req.body === undefined ? undefined : await collect(req.body);
+            const res = await safeFetch(target.href, { method, headers, ...(body !== undefined && { body }), signal }, o.net, { maxBytes: o.maxBytes });
+            const stream = res.body;
+            async function* chunks() {
+                if (stream === null)
+                    return;
+                try {
+                    for await (const c of stream)
+                        yield c;
+                }
+                catch (e) {
+                    if (e instanceof NetBodyTooLargeError)
+                        state.overLimit = true;
+                    throw e;
+                }
+            }
+            return {
+                url: target.href,
+                method,
+                statusCode: res.status,
+                statusMessage: res.statusText,
+                headers: Object.fromEntries(res.headers),
+                body: chunks(),
+            };
+        },
+    };
+    return { signal, http, url: loc.url.replace(/\/+$/, ""), state };
+}
+/** Maps anything thrown during an operation to a {@link GitSourceError} (the caller's abort stays). */
+function mapError(e, op, o, what) {
+    if (o.signal.aborted)
+        return o.signal.reason;
+    if (e instanceof GitSourceError)
+        return e;
+    if (op.state.overLimit || e instanceof NetBodyTooLargeError) {
+        return tooLarge(`${what}: the git server sent more than ${o.maxBytes} bytes`);
+    }
+    if (op.signal.aborted) {
+        return failed(`${what}: timed out after ${GIT_LIMITS.timeoutMs / 1000} s`, e);
+    }
+    if (e instanceof NetDeniedError) {
+        const netCode = marketplaceNetCode(e);
+        // GitLab and Gitea redirect a repo URL without `.git` to the one with it
+        const suffix = netCode === "marketplace.redirect" && !/\.git$/i.test(new URL(op.url).pathname);
+        return new GitSourceError("marketplace.git_failed", `${what}: ${e.message}${suffix ? " Use the repository URL ending in .git." : ""}`, {
+            cause: e,
+            ...(netCode !== undefined && { netCode }),
+            detail: { host: e.host, ...(suffix && { hint: "git_suffix" }) },
+        });
+    }
+    const cause = e?.cause;
+    if (cause instanceof NetDeniedError)
+        return mapError(cause, op, o, what);
+    const status = e?.data?.statusCode;
+    if (typeof status === "number")
+        return failed(`${what}: the git server answered ${status}`, e);
+    return failed(`${what}: ${errMsg(e)}`, e);
+}
+/**
+ * The commit to read (40 lower-case hex): `commit` when given (it wins over `ref`), otherwise the
+ * head of `ref` (a branch, a tag or a full `refs/…` name) or of the remote HEAD.
+ */
+export async function resolveGitCommit(loc, o) {
+    if (loc.commit !== undefined) {
+        if (!SHA_RE.test(loc.commit))
+            throw failed(`"${loc.commit}" is not a full commit sha`);
+        return loc.commit.toLowerCase();
+    }
+    const ref = loc.ref ?? "HEAD";
+    if (SHA_RE.test(ref))
+        return ref.toLowerCase();
+    const op = startOp(loc, o);
+    const what = `cannot list the refs of ${op.url}`;
+    let refs;
+    try {
+        const info = await git.getRemoteInfo2({ http: op.http, url: op.url, protocolVersion: 1 });
+        refs = info.refs ?? [];
+    }
+    catch (e) {
+        throw mapError(e, op, o, what);
+    }
+    const names = ref === "HEAD"
+        ? ["HEAD"]
+        : ref.startsWith("refs/")
+            ? [ref]
+            : [`refs/heads/${ref}`, `refs/tags/${ref}`];
+    for (const name of names) {
+        const r = refs.find((x) => x.ref === name);
+        if (r !== undefined) {
+            const oid = r.peeled ?? r.oid;
+            if (SHA_RE.test(oid))
+                return oid.toLowerCase();
+        }
+    }
+    throw failed(`${op.url}: ref "${ref}" not found`);
+}
+/** The delta's result size (the second varint of the delta header). */
+function deltaTargetSize(delta) {
+    let pos = 0;
+    const varint = () => {
+        let n = 0;
+        let shift = 0;
+        let c;
+        do {
+            if (pos >= delta.length || shift > 49)
+                throw failed("corrupt git pack: bad delta header");
+            c = delta[pos++];
+            n += (c & 0x7f) * 2 ** shift;
+            shift += 7;
+        } while (c & 0x80);
+        return n;
+    };
+    varint();
+    return varint();
+}
+/**
+ * Walks a pack (v2/v3) with bounded inflation before anything else expands it: object count and the
+ * declared content sizes (objects, and delta results) must fit; an object that inflates beyond its
+ * declared size is refused.
+ */
+export function scanPack(pack, maxUnpacked) {
+    const b = Buffer.from(pack.buffer, pack.byteOffset, pack.byteLength);
+    if (b.length < 32 || b.toString("latin1", 0, 4) !== "PACK")
+        throw failed("not a git pack");
+    const count = b.readUInt32BE(8);
+    if (count > GIT_LIMITS.maxObjects) {
+        throw tooLarge(`the git pack holds ${count} objects; at most ${GIT_LIMITS.maxObjects}`);
+    }
+    const end = b.length - 20;
+    let pos = 12;
+    let total = 0;
+    const truncated = () => failed("corrupt git pack: truncated");
+    for (let i = 0; i < count; i++) {
+        if (pos >= end)
+            throw truncated();
+        let c = b[pos++];
+        const type = (c >> 4) & 7;
+        let size = c & 15;
+        let shift = 4;
+        while (c & 0x80) {
+            if (pos >= end || shift > 49)
+                throw truncated();
+            c = b[pos++];
+            size += (c & 0x7f) * 2 ** shift;
+            shift += 7;
+        }
+        if (type === 6) {
+            do {
+                if (pos >= end)
+                    throw truncated();
+                c = b[pos++];
+            } while (c & 0x80);
+        }
+        else if (type === 7)
+            pos += 20;
+        else if (type < 1 || type > 4)
+            throw failed(`corrupt git pack: object type ${type}`);
+        if (size > maxUnpacked - total) {
+            throw tooLarge(`the git content is larger than ${maxUnpacked} bytes unpacked`);
+        }
+        let out;
+        try {
+            out = inflateSync(b.subarray(pos, end), {
+                info: true,
+                maxOutputLength: Math.max(size, 1),
+            });
+        }
+        catch (e) {
+            throw failed(`corrupt git pack: ${errMsg(e)}`, e);
+        }
+        if (out.buffer.length !== size)
+            throw failed("corrupt git pack: object size mismatch");
+        pos += out.engine.bytesWritten;
+        total += type >= 6 ? deltaTargetSize(out.buffer) : size;
+        if (total > maxUnpacked) {
+            throw tooLarge(`the git content is larger than ${maxUnpacked} bytes unpacked`);
+        }
+    }
+}
+const PACK_FILE_RE = /[/\\]objects[/\\]pack[/\\]pack-[0-9a-f]*\.pack$/;
+/** node fs for isomorphic-git, with the pack scanned before it is written (and then indexed). */
+function scanningFs(maxUnpacked) {
+    // isomorphic-git retries a failed write after creating the directory: scan each pack once
+    const verdicts = new WeakMap();
+    const scan = (data) => {
+        if (!verdicts.has(data)) {
+            try {
+                scanPack(data, maxUnpacked);
+                verdicts.set(data, null);
+            }
+            catch (e) {
+                verdicts.set(data, e);
+            }
+        }
+        const verdict = verdicts.get(data);
+        if (verdict !== null)
+            throw verdict;
+    };
+    return {
+        promises: {
+            ...fsp,
+            writeFile: (async (path, data, opts) => {
+                if (PACK_FILE_RE.test(path) && typeof data !== "string")
+                    scan(data);
+                return fsp.writeFile(path, data, opts);
+            }),
+        },
+    };
+}
+/** The message for a pinned commit the server would not send. */
+const refusedCommit = (commit) => `the server refused to serve commit ${commit}; pin a branch or tag tip instead`;
+/** isomorphic-git's error for a want the server did not answer (an unknown or unadvertised sha). */
+function refusedWant(e) {
+    const code = e?.code;
+    if (code === "NotFoundError")
+        return true;
+    return /not our ref|unadvertised object|want .* not valid/i.test(errMsg(e));
+}
+/** `path` as segments ([] = the repo root); undefined when it is not a safe relative path. */
+function pathSegments(path) {
+    if (path === undefined)
+        return [];
+    let p = path;
+    if (p.startsWith("./"))
+        p = p.slice(2);
+    p = p.replace(/\/$/, "");
+    if (p === "" || p === ".")
+        return [];
+    const segs = p.split("/");
+    return segs.every((s) => s !== "" && s !== "." && s !== ".." && !s.includes("\\") && !s.includes("\0"))
+        ? segs
+        : undefined;
+}
+/**
+ * The files under `path` at `commit` (paths relative to `path`, `/`-separated, sorted). Throws
+ * {@link GitSourceError}: `marketplace.git_failed` (network, server, missing commit or path),
+ * `marketplace.git_too_large` (limits), `marketplace.git_unsupported_entry` (symlink, submodule).
+ */
+export async function readGitTree(loc, o) {
+    return (await readGitTreeAndOids(loc, o)).files;
+}
+/**
+ * {@link readGitTree}, plus the git tree oids of directories at the same commit: `trees` gets the
+ * files read and returns directory paths relative to the repository root (`.` is the root); each
+ * one that exists and is a directory gets its tree oid (equal oids mean equal contents, so a
+ * plugin directory that did not change keeps its oid across commits).
+ */
+export async function readGitTreeAndOids(loc, o) {
+    if (!SHA_RE.test(loc.commit))
+        throw failed(`"${loc.commit}" is not a full commit sha`);
+    const commit = loc.commit.toLowerCase();
+    const segs = pathSegments(loc.path);
+    if (segs === undefined)
+        throw failed(`invalid path "${loc.path}" in the repository`);
+    const op = startOp(loc, o);
+    const what = `cannot read ${op.url} at ${commit.slice(0, 12)}`;
+    const maxUnpacked = GIT_LIMITS.unpackedFactor * o.maxBytes;
+    const fs = scanningFs(maxUnpacked);
+    const cache = {};
+    const gitdir = await fsp.mkdtemp(join(o.tempRoot ?? tmpdir(), "capybara-git-"));
+    try {
+        await git.init({ fs, gitdir, bare: true });
+        // fetch needs a remote with a refspec; the commit is fetched by sha and matches no refspec
+        await git.addRemote({ fs, gitdir, remote: "origin", url: op.url });
+        let res;
+        try {
+            res = await git.fetch({
+                fs,
+                http: op.http,
+                gitdir,
+                cache,
+                url: op.url,
+                ref: commit,
+                singleBranch: true,
+                depth: 1,
+                tags: false,
+            });
+        }
+        catch (e) {
+            // A commit that is not a ref tip needs the server to allow reachable-sha wants (GitHub does;
+            // GitLab / Gitea depend on their configuration); the server then sends nothing for it
+            if (refusedWant(e))
+                throw failed(`${what}: ${refusedCommit(commit)}`, e);
+            throw e;
+        }
+        if (res.fetchHead !== commit)
+            throw failed(`${what}: ${refusedCommit(commit)}`);
+        op.signal.throwIfAborted();
+        let c;
+        try {
+            ({ commit: c } = await git.readCommit({ fs, gitdir, oid: commit, cache }));
+        }
+        catch (e) {
+            // the server answered the fetch without the commit
+            if (refusedWant(e))
+                throw failed(`${what}: ${refusedCommit(commit)}`, e);
+            throw e;
+        }
+        let tree = c.tree;
+        const shown = [];
+        for (const seg of segs) {
+            shown.push(seg);
+            const { tree: entries } = await git.readTree({ fs, gitdir, oid: tree, cache });
+            const e = entries.find((x) => x.path === seg);
+            if (e === undefined)
+                throw failed(`${what}: ${shown.join("/")} not found`);
+            if (e.mode === "120000")
+                throw unsupported(`${shown.join("/")} is a symlink`, shown.join("/"));
+            if (e.type === "commit")
+                throw unsupported(`${shown.join("/")} is a submodule`, shown.join("/"));
+            if (e.type !== "tree")
+                throw failed(`${what}: ${shown.join("/")} is not a directory`);
+            tree = e.oid;
+        }
+        const files = new Map();
+        let bytes = 0;
+        // Every entry visited counts, trees included: a tree-only DAG (one subtree referenced many
+        // times at every level) is a handful of objects but exponentially many visits.
+        let visits = 0;
+        // Parsed trees by oid: a subtree referenced many times (a DAG, or identical directories) is
+        // read and parsed once; re-parsing it on every reference made a 20 000-entry walk cost
+        // hundreds of tree reads (seconds under load). The visit count above still bounds the walk.
+        const parsed = new Map();
+        const walk = async (oid, prefix) => {
+            op.signal.throwIfAborted();
+            let entries = parsed.get(oid);
+            if (entries === undefined) {
+                ({ tree: entries } = await git.readTree({ fs, gitdir, oid, cache }));
+                parsed.set(oid, entries);
+            }
+            for (const e of entries) {
+                if (++visits > GIT_LIMITS.maxObjects) {
+                    throw tooLarge(`the tree has more than ${GIT_LIMITS.maxObjects} entries`);
+                }
+                const name = e.path;
+                // biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are refused
+                if (name === "" || name === "." || name === ".." || /[/\\\u0000-\u001f\u007f]/.test(name)) {
+                    throw unsupported(`invalid entry name ${JSON.stringify(name)} in ${prefix || "."}`, prefix || ".");
+                }
+                const p = prefix === "" ? name : `${prefix}/${name}`;
+                if (o.include !== undefined && !o.include(p, e.type === "tree" ? "tree" : "blob"))
+                    continue;
+                if (e.type === "commit")
+                    throw unsupported(`${p} is a submodule`, p);
+                if (e.mode === "120000")
+                    throw unsupported(`${p} is a symlink`, p);
+                if (e.type === "tree") {
+                    await walk(e.oid, p);
+                    continue;
+                }
+                if (e.type !== "blob")
+                    throw unsupported(`${p} is a ${e.type}`, p);
+                if (files.size >= GIT_LIMITS.maxFiles) {
+                    throw tooLarge(`more than ${GIT_LIMITS.maxFiles} files`);
+                }
+                const { blob } = await git.readBlob({ fs, gitdir, oid: e.oid, cache });
+                bytes += blob.byteLength;
+                if (bytes > maxUnpacked)
+                    throw tooLarge(`the files are larger than ${maxUnpacked} bytes`);
+                files.set(p, blob);
+                op.signal.throwIfAborted();
+            }
+        };
+        await walk(tree, "");
+        const sorted = new Map([...files.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+        const trees = new Map();
+        for (const dir of o.trees?.(sorted) ?? []) {
+            const want = pathSegments(dir === "." ? undefined : dir);
+            if (want === undefined)
+                continue;
+            let oid = c.tree;
+            for (const seg of want) {
+                const { tree: entries } = await git.readTree({ fs, gitdir, oid, cache });
+                const e = entries.find((x) => x.path === seg);
+                oid = e?.type === "tree" && e.mode !== "120000" ? e.oid : undefined;
+                if (oid === undefined)
+                    break;
+            }
+            if (oid !== undefined)
+                trees.set(dir, oid);
+        }
+        return { files: sorted, trees };
+    }
+    catch (e) {
+        throw mapError(e, op, o, what);
+    }
+    finally {
+        await fsp.rm(gitdir, { recursive: true, force: true });
+    }
+}

package/dist/catalog/marketplace-fetch.d.ts

@@ -0,0 +1,99 @@
+import { type MarketplaceManifest } from "@capybara-hq/plugin-sdk";
+import type { KernelConfig } from "../config/schema.js";
+import { type LookupFn, NetDeniedError, type NetPolicy } from "../net/public-address.js";
+/**
+ * Fetching a marketplace manifest `marketplace.json` (C26, spec §5.2) and a marketplace's archive
+ * sources. The URLs come from an enterprise admin or the config, but responses are always hostile
+ * input:
+ * - https only (`allowInsecureLoopback`, tests only, allows http on loopback addresses), no user
+ *   info in the URL;
+ * - every request goes through `net/safeFetch`: the host must resolve to public addresses (or be
+ *   exempt by `marketplaces.allowPrivateHosts` / the npm registry origin) and the connection is
+ *   pinned to the checked address;
+ * - redirects are not followed (a 3xx fails): one redirect could otherwise send the request (and the
+ *   token) elsewhere;
+ * - a timeout, and the body is counted while read and aborted past `maxBytes`;
+ * - the manifest is validated by the SDK's `parseMarketplaceManifest`; an invalid one is refused as
+ *   a whole (the caller keeps the previous entries);
+ * - the token is sent only when the request URL has the same origin as `tokenOrigin` (the
+ *   marketplace's main URL), never to a mirror on another origin.
+ */
+/** The API error code for a download the network rules refused. */
+export type MarketplaceNetCode = "marketplace.private_address" | "marketplace.redirect";
+/**
+ * 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 declare function marketplaceNetCode(e: NetDeniedError): MarketplaceNetCode | undefined;
+/** The network rules for marketplace downloads from the kernel config. */
+export declare function marketplaceNetPolicy(config: KernelConfig): NetPolicy;
+/**
+ * The fetch failed (network, HTTP status, redirect, size, timeout). English message, no token.
+ * `code` is set when the network rules refused the request.
+ */
+export declare class MarketplaceFetchError extends Error {
+    readonly code: MarketplaceNetCode | undefined;
+    /** The host the network rules refused (with `code`). */
+    readonly host: string | undefined;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        code?: MarketplaceNetCode;
+        host?: string;
+    });
+}
+/** The response is not a valid manifest (JSON or schema). */
+export declare class MarketplaceInvalidError extends Error {
+    readonly issues: string[];
+    constructor(message: string, issues: string[]);
+}
+export interface MarketplaceFetchOptions {
+    /** The ETag of the last successful fetch (sent as `If-None-Match`). */
+    etag?: string | null;
+    token?: string;
+    /** The token goes only to this origin (the marketplace's main URL). */
+    tokenOrigin?: string;
+    maxBytes: number;
+    timeoutMs: number;
+    net: NetPolicy;
+    /** Tests only: replaces the DNS lookup. */
+    lookup?: LookupFn;
+    signal: AbortSignal;
+}
+export type MarketplaceFetchResult = {
+    status: "not_modified";
+} | {
+    status: "ok";
+    manifest: MarketplaceManifest;
+    etag: string | null;
+};
+/**
+ * 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 declare function marketplaceUrlProblem(url: string, allowInsecureLoopback: boolean): string | null;
+/**
+ * Fetches and validates one `marketplace.json`. Throws {@link MarketplaceFetchError} or
+ * {@link MarketplaceInvalidError}.
+ */
+export declare function fetchMarketplaceManifest(url: string, o: MarketplaceFetchOptions): Promise<MarketplaceFetchResult>;
+/**
+ * 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 declare function fetchMarketplaceArchive(archive: {
+    url: string;
+    integrity: string;
+}, o: {
+    maxBytes: number;
+    timeoutMs: number;
+    net: NetPolicy;
+    lookup?: LookupFn;
+    signal?: AbortSignal;
+}): Promise<{
+    bytes: Uint8Array;
+    integrity: string;
+}>;